diff --git a/config.toml b/config.toml index 6581a06c1..5a3507237 100644 --- a/config.toml +++ b/config.toml @@ -13,8 +13,8 @@ pygmentsStyle = "fruity" # Versions (folder-based) [params.versions] -current = "17.0" -next = "18.0" +current = "18.0" +next = "19.0" # end Versions diff --git a/content/en/docs/18.0/_index.md b/content/en/docs/18.0/_index.md index 6c319e0c4..28c8396d8 100644 --- a/content/en/docs/18.0/_index.md +++ b/content/en/docs/18.0/_index.md @@ -1,7 +1,7 @@ --- -title: v18.0 (Development) +title: v18.0 (RC) description: > - Under construction, development release. + Release Candidate. Everything you need to know about scaling MySQL with Vitess. notoc: true cascade: diff --git a/content/en/docs/18.0/get-started/local.md b/content/en/docs/18.0/get-started/local.md index 1667580df..2eb1bc039 100644 --- a/content/en/docs/18.0/get-started/local.md +++ b/content/en/docs/18.0/get-started/local.md @@ -65,8 +65,8 @@ 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 -file=vitess-${version}-70a9466.tar.gz +version=18.0.0-rc1 +file=vitess-${version}-6ab165a.tar.gz wget https://github.com/vitessio/vitess/releases/download/v${version}/${file} tar -xzf ${file} cd ${file/.tar.gz/} diff --git a/content/en/docs/19.0/_index.md b/content/en/docs/19.0/_index.md new file mode 100644 index 000000000..150884132 --- /dev/null +++ b/content/en/docs/19.0/_index.md @@ -0,0 +1,11 @@ +--- +title: v19.0 (Development) +description: > + Under construction, development release. + Everything you need to know about scaling MySQL with Vitess. +notoc: true +cascade: + version: v19.0 +weight: 81 +--- + diff --git a/content/en/docs/19.0/concepts/_index.md b/content/en/docs/19.0/concepts/_index.md new file mode 100644 index 000000000..3282daf67 --- /dev/null +++ b/content/en/docs/19.0/concepts/_index.md @@ -0,0 +1,6 @@ +--- +title: Concepts +description: Learn core Vitess concepts and terminology +aliases: ['/docs/overview/concepts/'] +weight: 3 +--- diff --git a/content/en/docs/19.0/concepts/cell.md b/content/en/docs/19.0/concepts/cell.md new file mode 100644 index 000000000..f6d16f088 --- /dev/null +++ b/content/en/docs/19.0/concepts/cell.md @@ -0,0 +1,10 @@ +--- +title: Cell +description: Data center, availability zone or group of computing resources +--- + +A *cell* is a group of servers and network infrastructure collocated in an area, and isolated from failures in other cells. It is typically either a full data center or a subset of a data center, sometimes called a *zone* or *availability zone*. Vitess gracefully handles cell-level failures, such as when a cell is cut off the network. + +Each cell in a Vitess implementation has a [local topology service](../topology-service), which is hosted in that cell. The topology service contains most of the information about the Vitess tablets in its cell. This enables a cell to be taken down and rebuilt as a unit. + +Vitess limits cross-cell traffic for both data and metadata. While it may be useful to also have the ability to route read traffic to individual cells, Vitess currently serves reads only from the local cell. Writes will go cross-cell when necessary, to wherever the primary for that shard resides. diff --git a/content/en/docs/19.0/concepts/execution-plans.md b/content/en/docs/19.0/concepts/execution-plans.md new file mode 100644 index 000000000..d6cb5b07a --- /dev/null +++ b/content/en/docs/19.0/concepts/execution-plans.md @@ -0,0 +1,33 @@ +--- +title: Execution Plans +--- + +Vitess parses queries at both the VTGate and VTTablet layer in order to evaluate the best method to execute a query. This evaluation is known as query planning, and results in a _query execution plan_. + +The Execution Plan is dependent on both the query and the associated [VSchema](../vschema). One of the underlying goals of Vitess' planning strategy is to push down as much work as possible to the underlying MySQL instances. When this is not possible, Vitess will use a plan that collects input from multiple sources and merges the results to produce the correct query result. + +### Evaluation Model + +An execution plan consists of operators, each of which implements a specific piece of work. The operators combine into a tree-like structure, which represents the overall execution plan. The plan represents each operator as a node in the tree. Each operator takes as input zero or more rows, and produces as output zero or more rows. This means that the output from one operator becomes the input for the next operator. Operators that join two branches in the tree combine input from two incoming streams and produce a single output. + +Evaluation of the execution plan begins at the leaf nodes of the tree. Leaf nodes pull in data from VTTablet, the Topology Service, and in some cases are also able to evaluate expression values locally. Each leaf node will not have input from other operators, and pipe in any nodes they produce into their parent nodes. The parents nodes will then pipe in nodes to their parent nodes, all the way up to a root node. The root node produces the final results of the query and delivers the results to the user. + +### Routing Operators + +A routing operator in an execution plan instructs Vitess which destination to send a piece of work to. Typically a routing operator will tell Vitess which keyspace to use when executing the piece of work, whether or not the keyspace is sharded, and, in the case of sharded keyspaces, which vindex to use. + +### Scatter Queries + +A routing operator which specifies a sharded keyspace, but which does not specify a vindex, will "scatter" to all shards in a sharded keyspace. A "scatter" query contains one or more pieces of work routed to a sharded keyspace, but which cannot be routed using a vindex. + +Note that not all queries which are sent to multiple (or all) shards in a sharded keyspace are considered scatter queries. + +### Observing Execution Plans + +Cached execution plans can be observed at the VTGate level by browsing the `/queryz` end point. + +Starting with Vitess 6, individual statement plans can also be observed with `EXPLAIN FORMAT=vitess `. + +**Related Vitess Documentation** + +* [VTGate](../vtgate) diff --git a/content/en/docs/19.0/concepts/img/VStream.svg b/content/en/docs/19.0/concepts/img/VStream.svg new file mode 100644 index 000000000..47b54d4a1 --- /dev/null +++ b/content/en/docs/19.0/concepts/img/VStream.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/19.0/concepts/keyspace-id.md b/content/en/docs/19.0/concepts/keyspace-id.md new file mode 100644 index 000000000..a4ac032d7 --- /dev/null +++ b/content/en/docs/19.0/concepts/keyspace-id.md @@ -0,0 +1,10 @@ +--- +title: Keyspace ID +--- + +The *keyspace ID* is the value that is used to decide on which shard a given row lives. [Range-based Sharding](../../reference/features/sharding/#key-ranges-and-partitions) refers to creating shards that each cover a particular range of keyspace IDs. + +Using this technique means you can split a given shard by replacing it with two or more new shards that combine to cover the original range of keyspace IDs, without having to move any records in other shards. + +The keyspace ID itself is computed using a function of some column in your data, such as the user ID. Vitess allows you to choose from a variety of functions ([vindexes](../../reference/features/vindexes/)) to perform this mapping. This allows you to choose the right one to achieve optimal distribution of the data across shards. + diff --git a/content/en/docs/19.0/concepts/keyspace.md b/content/en/docs/19.0/concepts/keyspace.md new file mode 100644 index 000000000..c22c61fd5 --- /dev/null +++ b/content/en/docs/19.0/concepts/keyspace.md @@ -0,0 +1,8 @@ +--- +title: Keyspace +--- + +A *keyspace* is a logical database. If you're using [sharding](http://en.wikipedia.org/wiki/Shard_(database_architecture)), a keyspace maps to multiple MySQL databases; if you're not using sharding, a keyspace maps directly to a MySQL database name. In either case, a keyspace appears as a single database from the standpoint of the application. + +Reading data from a keyspace is just like reading from a MySQL database. However, depending on the consistency requirements of the read operation, Vitess might fetch the data from a primary database or from a replica. By routing each query to the appropriate database, Vitess allows your code to be structured as if it were reading from a single MySQL database. + diff --git a/content/en/docs/19.0/concepts/move-tables.md b/content/en/docs/19.0/concepts/move-tables.md new file mode 100644 index 000000000..ced9abf99 --- /dev/null +++ b/content/en/docs/19.0/concepts/move-tables.md @@ -0,0 +1,26 @@ +--- +title: MoveTables +--- + +MoveTables is a new workflow based on VReplication. It enables you to relocate tables between keyspaces, and therefore physical MySQL instances, without downtime. + +## Identifying Candidate Tables + +It is recommended to keep tables that need to join on each other in the same keyspace, so typical candidates for a MoveTables operation are a set of tables which logically group together or are otherwise isolated. + +If you have multiple groups of tables as candidates, which makes the most sense to move may depend on the specifics of your environment. For example, a larger table will take more time to move, but in doing so you might be able to utilize additional or newer hardware which has more headroom before you need to perform additional operations such as sharding. + +Similarly, tables that are updated at a more frequent rate could increase the move time. + +### Impact to Production Traffic + +Internally, a MoveTables operation is comprised of both a table copy and a subscription to all changes made to the table. Vitess uses batching to improve the performance of both table copying and applying subscription changes, but you should expect that tables with lighter modification rates to move faster. + +During the active move process, data is copied from replicas instead of the primary server. This helps ensure minimal production traffic impact. + +During the `SwitchTraffic` phase of the MoveTables operation, for primary tablets, Vitess may be briefly unavailable. This unavailability is usually a few seconds, but will be higher in the event that your system has a high replication delay from primary to replica(s). + + +**Related Vitess Documentation** + +* [MoveTables User Guide](../../user-guides/migration/move-tables) diff --git a/content/en/docs/19.0/concepts/query-rewriting.md b/content/en/docs/19.0/concepts/query-rewriting.md new file mode 100644 index 000000000..8a62ac0f7 --- /dev/null +++ b/content/en/docs/19.0/concepts/query-rewriting.md @@ -0,0 +1,248 @@ +--- +title: Query Rewriting +--- + +Vitess works hard to create an illusion of the user having a single connection to a single database. +In reality, a single query might interact with multiple databases and may use multiple connections to the same database. +Here we'll go over what Vitess does and how it might impact you. + +### Query splitting + +A complicated query with a cross shard join might need to first fetch information from a tablet keeping vindex lookup tables. Then use this information to query two different shards for more data and subsequently join the incoming results into a single result that the user receives. +The queries that MySQL gets are often just pieces of the original query, and the final result will get assembled at the vtgate level. + +### Connection Pooling + +When a tablet talks with a MySQL to execute a query on behalf of a user, it does not use a dedicated connection per user, and instead will share the underlying connection between users. +This means that it's not safe to store any state in the session as you can't be sure it will continue executing queries on the same connection, and you can't be sure if this connection will be used by other users later on. + +### User-Defined Variables + +User defined variables are kept in the session state when working with MySQL. +You can assign values to them using SET: + +```sql +SET @my_user_variable = 'foobar' +``` + +And later there can be queries using for example SELECT: + +```sql +> SELECT @my_user_variable; ++-------------------+ +| @my_user_variable | ++-------------------+ +| foobar | ++-------------------+ +``` + +If you execute these queries against a VTGate, the first `SET` query is not sent to MySQL. +Instead, it is evaluated in the VTGate, and VTGate will keep this state for you. +The second query is also not sent down. Trivial queries such as this one are actually fully executed on VTGate. + +If we try a more complicated query that requires data from MySQL, VTGate will rewrite the query before sending it down. +If we were to write something like: + +```sql +WHERE col = @my_user_variable +``` + +What MySQL will see is: + +```sql +WHERE col = 'foobar' +``` + +This way, no session state is needed to evaluate the query in MySQL. + +### Server System Variables + +A user might also want to change one of the many different system variables that MySQL exposes. +Vitess handles system variables in one of five different ways: + + * *No op*. For some settings, Vitess will just silently ignore the setting. This is for system variables that don't make much sense in a sharded setting, and don't change the behaviour of MySQL in an interesting way. + * *Check and fail if not already set*. These are settings that should not change, but Vitess will allow SET statements that try to set the variable to whatever it already is. + * *Not supported*. For these settings, attempting to change them will always result in an error. + * *Vitess aware*. These are settings that change Vitess' behaviour, and are not sent down to MySQL + * *Reserved connection*. For some settings, it makes sense to allow them to be set, but it makes using a shared connection for this user much harder. By default, Vitess will first apply these system variables that are set, and then keep the connection dedicated for this user. Connection pooling is important for the performance of Vitess, so this should not be the normal way to run applications on Vitess. Just make sure that the global variable is set to the same value the application will set it to, and Vitess can use connection pooling. Vitess now has support for connection-pooling even for these settings that originally required reserved connections. You can read more about it [here](../../reference/query-serving/reserved-conn/#settings-pool-and-reserved-connections). + +In addition to this, Vitess makes sure that @@version includes both the emulated MySQL version and the Vitess version, such as: `5.7.9-vitess-14.0.0`. This value can be changed by using the vtgate flag `--mysql_server_version`. + + +### Special functions + +There are a few special functions that Vitess handles without delegating to MySQL. + + * `DATABASE()` - The keyspace name and the underlying database names do not have to be equal. Vitess will rewrite these calls to use the literal string for the keyspace name. (This also applies to the synonym `SCHEMA()`) + * `ROW_COUNT()` and `FOUND_ROWS()` - These functions returns how many rows the last query affected/returned. Since this might have been executed on a different connection, these get rewritten to use the literal value of the number of returned rows. + * `LAST_INSERT_ID()` - Much like `FOUND_ROWS()`, we can't trust a pooled connection for these function calls, so they get rewritten before hitting MySQL. + +### Reference + +Here is a list of all the system variables that are handled by Vitess and how they are handled. + +| *System variable* | *Handled* | +|-----------------------------------------|----------------| +| autocommit | VitessAware | +| client_found_rows | VitessAware | +| skip_query_plan_cache | VitessAware | +| tx_read_only | VitessAware | +| transaction_read_only | VitessAware | +| sql_select_limit | VitessAware | +| transaction_mode | VitessAware | +| ddl_strategy | VitessAware | +| workload | VitessAware | +| charset | VitessAware | +| names | VitessAware | +| session_uuid | VitessAware | +| migration_context | VitessAware | +| enable_system_settings | VitessAware | +| read_after_write_gtid | VitessAware | +| read_after_write_timeout | VitessAware | +| session_track_gtids | VitessAware | +| query_timeout | VitessAware | +| transaction_isolation | VitessAware | +| tx_isolation | VitessAware | +| big_tables | NoOp | +| bulk_insert_buffer_size | NoOp | +| debug | NoOp | +| default_storage_engine | NoOp | +| default_tmp_storage_engine | NoOp | +| innodb_strict_mode | NoOp | +| innodb_support_xa | NoOp | +| innodb_table_locks | NoOp | +| innodb_tmpdir | NoOp | +| join_buffer_size | NoOp | +| keep_files_on_create | NoOp | +| lc_messages | NoOp | +| long_query_time | NoOp | +| low_priority_updates | NoOp | +| max_delayed_threads | NoOp | +| max_insert_delayed_threads | NoOp | +| multi_range_count | NoOp | +| net_buffer_length | NoOp | +| new | NoOp | +| query_cache_type | NoOp | +| query_cache_wlock_invalidate | NoOp | +| query_prealloc_size | NoOp | +| sql_buffer_result | NoOp | +| transaction_alloc_block_size | NoOp | +| wait_timeout | NoOp | +| audit_log_read_buffer_size | NotSupported | +| auto_increment_increment | NotSupported | +| auto_increment_offset | NotSupported | +| binlog_direct_non_transactional_updates | NotSupported | +| binlog_row_image | NotSupported | +| binlog_rows_query_log_events | NotSupported | +| innodb_ft_enable_stopword | NotSupported | +| innodb_ft_user_stopword_table | NotSupported | +| max_points_in_geometry | NotSupported | +| max_sp_recursion_depth | NotSupported | +| myisam_repair_threads | NotSupported | +| myisam_sort_buffer_size | NotSupported | +| myisam_stats_method | NotSupported | +| ndb_allow_copying_alter_table | NotSupported | +| ndb_autoincrement_prefetch_sz | NotSupported | +| ndb_blob_read_batch_bytes | NotSupported | +| ndb_blob_write_batch_bytes | NotSupported | +| ndb_deferred_constraints | NotSupported | +| ndb_force_send | NotSupported | +| ndb_fully_replicated | NotSupported | +| ndb_index_stat_enable | NotSupported | +| ndb_index_stat_option | NotSupported | +| ndb_join_pushdown | NotSupported | +| ndb_log_bin | NotSupported | +| ndb_log_exclusive_reads | NotSupported | +| ndb_row_checksum | NotSupported | +| ndb_use_exact_count | NotSupported | +| ndb_use_transactions | NotSupported | +| ndbinfo_max_bytes | NotSupported | +| ndbinfo_max_rows | NotSupported | +| ndbinfo_show_hidden | NotSupported | +| ndbinfo_table_prefix | NotSupported | +| old_alter_table | NotSupported | +| preload_buffer_size | NotSupported | +| rbr_exec_mode | NotSupported | +| sql_log_off | NotSupported | +| thread_pool_high_priority_connection | NotSupported | +| thread_pool_prio_kickup_timer | NotSupported | +| transaction_write_set_extraction | NotSupported | +| default_week_format | ReservedConn | +| end_markers_in_json | ReservedConn | +| eq_range_index_dive_limit | ReservedConn | +| explicit_defaults_for_timestamp | ReservedConn | +| foreign_key_checks | ReservedConn | +| group_concat_max_len | ReservedConn | +| information_schema_stats_expiry | ReservedConn | +| max_heap_table_size | ReservedConn | +| max_seeks_for_key | ReservedConn | +| max_tmp_tables | ReservedConn | +| min_examined_row_limit | ReservedConn | +| old_passwords | ReservedConn | +| optimizer_prune_level | ReservedConn | +| optimizer_search_depth | ReservedConn | +| optimizer_switch | ReservedConn | +| optimizer_trace | ReservedConn | +| optimizer_trace_features | ReservedConn | +| optimizer_trace_limit | ReservedConn | +| optimizer_trace_max_mem_size | ReservedConn | +| optimizer_trace_offset | ReservedConn | +| parser_max_mem_size | ReservedConn | +| profiling | ReservedConn | +| profiling_history_size | ReservedConn | +| query_alloc_block_size | ReservedConn | +| range_alloc_block_size | ReservedConn | +| range_optimizer_max_mem_size | ReservedConn | +| read_buffer_size | ReservedConn | +| read_rnd_buffer_size | ReservedConn | +| show_create_table_verbosity | ReservedConn | +| show_old_temporals | ReservedConn | +| sort_buffer_size | ReservedConn | +| sql_big_selects | ReservedConn | +| sql_mode | ReservedConn | +| sql_notes | ReservedConn | +| sql_quote_show_create | ReservedConn | +| sql_safe_updates | ReservedConn | +| sql_warnings | ReservedConn | +| time_zone | ReservedConn | +| tmp_table_size | ReservedConn | +| transaction_prealloc_size | ReservedConn | +| unique_checks | ReservedConn | +| updatable_views_with_limit | ReservedConn | +| binlog_format | CheckAndIgnore | +| block_encryption_mode | CheckAndIgnore | +| character_set_client | CheckAndIgnore | +| character_set_connection | CheckAndIgnore | +| character_set_database | CheckAndIgnore | +| character_set_filesystem | CheckAndIgnore | +| character_set_results | CheckAndIgnore | +| character_set_server | CheckAndIgnore | +| collation_connection | CheckAndIgnore | +| collation_database | CheckAndIgnore | +| collation_server | CheckAndIgnore | +| completion_type | CheckAndIgnore | +| div_precision_increment | CheckAndIgnore | +| innodb_lock_wait_timeout | CheckAndIgnore | +| interactive_timeout | CheckAndIgnore | +| lc_time_names | CheckAndIgnore | +| lock_wait_timeout | CheckAndIgnore | +| max_allowed_packet | CheckAndIgnore | +| max_error_count | CheckAndIgnore | +| max_execution_time | CheckAndIgnore | +| max_join_size | CheckAndIgnore | +| max_length_for_sort_data | CheckAndIgnore | +| max_sort_length | CheckAndIgnore | +| max_user_connections | CheckAndIgnore | +| net_read_timeout | CheckAndIgnore | +| net_retry_count | CheckAndIgnore | +| net_write_timeout | CheckAndIgnore | +| session_track_schema", boolean: | CheckAndIgnore | +| session_track_state_change", boolean: | CheckAndIgnore | +| session_track_system_variables | CheckAndIgnore | +| session_track_transaction_info | CheckAndIgnore | +| sql_auto_is_null", boolean: | CheckAndIgnore | +| version_tokens_session | CheckAndIgnore | + +**Related Vitess Documentation** + +* [VTGate](../vtgate) diff --git a/content/en/docs/19.0/concepts/replication-graph.md b/content/en/docs/19.0/concepts/replication-graph.md new file mode 100644 index 000000000..2a88f88f3 --- /dev/null +++ b/content/en/docs/19.0/concepts/replication-graph.md @@ -0,0 +1,6 @@ +--- +title: Replication Graph +--- + +The *replication graph* identifies the relationships between primary databases and their respective replicas. During a failover, the replication graph enables Vitess to point all existing replicas to a newly designated primary database so that replication can continue. + diff --git a/content/en/docs/19.0/concepts/shard.md b/content/en/docs/19.0/concepts/shard.md new file mode 100644 index 000000000..375aa9ddf --- /dev/null +++ b/content/en/docs/19.0/concepts/shard.md @@ -0,0 +1,46 @@ +--- +title: Shard +--- + +A *shard* is a subset of a keyspace. A keyspace will always contain one or more shards. A shard typically contains one MySQL primary and potentially many MySQL replicas. + +Each MySQL instance within a shard has identical data (if we ignore any replication lag). The replicas can serve read-only traffic (with eventual consistency guarantees), execute long-running data analysis queries, or perform administrative tasks (backup, restore, diff, etc.). + +An *unsharded* keyspace is a keyspace with only a single shard. Vitess names the shard `0` (or sometimes `-`) by convention. When sharded, a keyspace has `N` shards with non-overlapping data. The number of shards in a keyspace can vary depending on the use-case and load characteristics, some Vitess users have hundreds of shards in some keyspaces. + +## Shard Naming + +Shard names have the following characteristics: + +* They represent a range in unsigned integer space, where the left number is included, but the right is not. +* Their notation is hexadecimal. +* They are left justified, and right-padded with zeros. +* A `-` prefix means: anything less than the right value. +* A `-` postfix means: anything greater than or equal to the LHS value. +* A plain `-` denotes the full keyrange. + +Thus: `-80` == `00-80` == `0000-8000` == `000000-800000` == `0000000000000000-8000000000000000` + +`80-` is not the same as `80-FF`. This is why: + +`80-FF` == `8000-FF00`. Therefore `FFFF` will be out of the `80-FF` range. + +`80-` means: ‘anything greater than or equal to `0x80` + +A `hash` type vindex produces an unsigned 64 bit integer as output. This means that all integers **less** than `0x8000000000000000` will fall in shard `-80`. Any number with the highest bit set will be >= `0x8000000000000000`, and will therefore belong to shard `80-`. + +This left-justified approach allows you to have keyspace ids of arbitrary length. However, the most significant bits are the ones on the left. + +For example an `md5` hash produces 16 bytes. That can also be used as a keyspace id. + +A `varbinary` of arbitrary length can also be mapped as is to a keyspace id. This is what the `binary` vindex does. + +## Resharding + +Vitess supports [resharding](../../user-guides/configuration-advanced/resharding), in which the number of shards is changed on a live cluster. This can be either splitting one or more shards into smaller pieces, or merging neighboring shards into bigger pieces. + +During resharding, the data in the source shards is copied into the destination shards, allowed to catch up on replication, and then compared against the original to ensure data integrity. Then the live serving infrastructure is shifted to the destination shards, and the source shards are deleted. + +**Related Vitess Documentation** + +* [Resharding User Guide](../../user-guides/configuration-advanced/resharding) diff --git a/content/en/docs/19.0/concepts/tablet.md b/content/en/docs/19.0/concepts/tablet.md new file mode 100644 index 000000000..3f4ae798d --- /dev/null +++ b/content/en/docs/19.0/concepts/tablet.md @@ -0,0 +1,20 @@ +--- +title: Tablet +--- + +A *tablet* is a combination of a `mysqld` process and a corresponding `vttablet` process, usually running on the same machine. Each tablet is assigned a *tablet type*, which specifies what role it currently performs. + +Queries are routed to a tablet via a [VTGate](../vtgate) server. + +## Tablet Types + +See the user guide [VTTablet Modes](../../user-guides/configuration-basic/vttablet-mysql/) for more information. + +* **primary** - A *replica* tablet that happens to currently be the MySQL primary for its shard. +* **master** - Same as **primary**. Deprecated. +* **replica** - A MySQL replica that is eligible to be promoted to *primary*. Conventionally, these are reserved for serving live, user-facing requests (like from the website's frontend). +* **rdonly** - A MySQL replica that cannot be promoted to *primary*. Conventionally, these are used for background processing jobs, such as taking backups, dumping data to other systems, heavy analytical queries and MapReduce. +* **backup** - A tablet that has stopped replication at a consistent snapshot, so it can upload a new backup for its shard. After it finishes, it will resume replication and return to its previous type. +* **restore** - A tablet that has started up with no data, and is in the process of restoring itself from the latest backup. After it finishes, it will begin replicating at the GTID position of the backup, and become either *replica* or *rdonly*. +* **drained** - A tablet that has been reserved by a Vitess background process (such as rdonly tablets for resharding). + diff --git a/content/en/docs/19.0/concepts/topology-service.md b/content/en/docs/19.0/concepts/topology-service.md new file mode 100644 index 000000000..3591bdcdd --- /dev/null +++ b/content/en/docs/19.0/concepts/topology-service.md @@ -0,0 +1,30 @@ +--- +title: Topology Service +description: Also known as the TOPO or lock service +--- + +The [*Topology Service*](../../user-guides/configuration-basic/global-topo/) is a set of backend processes running on different servers. Those servers store topology data and provide a distributed locking service. + +Vitess uses a plug-in system to support various backends for storing topology data, which are assumed to provide a distributed, consistent key-value store. The default topology service plugin is `etcd2`. + +The topology service exists for several reasons: + +* It enables tablets to coordinate among themselves as a cluster. +* It enables Vitess to discover tablets, so it knows where to route queries. +* It stores Vitess configuration provided by the database administrator that is needed by many different servers in the cluster, and that must persist between server restarts. + +A Vitess cluster has one global topology service, and a local topology service in each cell. + +## Global Topology + +The global topology service stores Vitess-wide data that does not change frequently. Specifically, it contains data about keyspaces and shards as well as the primary tablet alias for each shard. + +The global topology is used for some operations, including reparenting and resharding. By design, the global topology service is not used a lot. + +In order to survive any single cell going down, the global topology service should have nodes in multiple cells, with enough to maintain quorum in the event of a cell failure. + +## Local Topology + +Each local topology contains information related to its own cell. Specifically, it contains data about tablets in the cell, the keyspace graph for that cell, and the replication graph for that cell. + +The local topology service must be available for Vitess to discover tablets and adjust routing as tablets come and go. However, no calls to the topology service are made in the critical path of serving a query at steady state. That means queries are still served during temporary unavailability of topology. diff --git a/content/en/docs/19.0/concepts/vschema.md b/content/en/docs/19.0/concepts/vschema.md new file mode 100644 index 000000000..5df75980b --- /dev/null +++ b/content/en/docs/19.0/concepts/vschema.md @@ -0,0 +1,9 @@ +--- +title: VSchema +--- + +A [VSchema](../../reference/features/vschema) allows you to describe how data is organized within keyspaces and shards. This information is used for routing queries, and also during resharding operations. + +For a Keyspace, you can specify if it's sharded or not. For sharded keyspaces, you can specify the list of vindexes for each table. + +Vitess also supports [sequence generators](../../reference/features/vitess-sequences/) that can be used to generate new ids that work like MySQL auto increment columns. The VSchema allows you to associate table columns to sequence tables. If no value is specified for such a column, then VTGate will know to use the sequence table to generate a new value for it. diff --git a/content/en/docs/19.0/concepts/vstream.md b/content/en/docs/19.0/concepts/vstream.md new file mode 100644 index 000000000..efa0db7aa --- /dev/null +++ b/content/en/docs/19.0/concepts/vstream.md @@ -0,0 +1,26 @@ +--- +title: VStream +--- + + +VStream is a change notification service accessible via VTGate. The purpose of +VStream is to provide equivalent information to the MySQL binary logs from the +underlying MySQL shards of the Vitess cluster. gRPC clients, including Vitess +components like VTTablets, can subscribe to a VStream to receive change events +from other shards. The VStream pulls events from one or more VStreamer +instances on VTTablet instances, which in turn pulls events from the binary +log of the underlying MySQL instance. This allows for efficient execution of +functions such as VReplication where a subscriber can indirectly receive +events from the binary logs of one or more MySQL instance shards, and then +apply it to a target instance. A user can leverage VStream to obtain in-depth +information about data change events for a given Vitess keyspace, shard, and +position. A single VStream can also consolidate change events from multiple +shards in a keyspace, making it a convenient tool to feed a CDC (Change Data +Capture) process downstream from your Vitess datastore. + + +For reference, please refer to the diagram below: + +![VStream diagram](/img/VStream.svg) + +Note: A VStream is distinct from a VStreamer. The former is located on the VTGate and the latter is located on the VTTablet. diff --git a/content/en/docs/19.0/concepts/vtctl.md b/content/en/docs/19.0/concepts/vtctl.md new file mode 100644 index 000000000..339ac96aa --- /dev/null +++ b/content/en/docs/19.0/concepts/vtctl.md @@ -0,0 +1,9 @@ +--- +title: vtctl +--- + +**vtctl** is a command-line tool used to administer a Vitess cluster. It is available as both a standalone tool (`vtctl`) and client-server (`vtctldclient` in combination with `vtctld`). Using client-server is recommended, as it provides an additional layer of security when using the client remotely. + +Using vtctl, you can identify primary and replica databases, create tables, initiate failovers, perform resharding operations, and so forth. + +As vtctl performs operations, the Topology Service is updated as needed. Other Vitess servers observe those changes and react accordingly. For example, if you use vtctl to fail over to a new primary database, vtgate sees the change and directs future write operations to the new primary. diff --git a/content/en/docs/19.0/concepts/vtctld.md b/content/en/docs/19.0/concepts/vtctld.md new file mode 100644 index 000000000..2f39c54d6 --- /dev/null +++ b/content/en/docs/19.0/concepts/vtctld.md @@ -0,0 +1,7 @@ +--- +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. diff --git a/content/en/docs/19.0/concepts/vtgate.md b/content/en/docs/19.0/concepts/vtgate.md new file mode 100644 index 000000000..3e441bb25 --- /dev/null +++ b/content/en/docs/19.0/concepts/vtgate.md @@ -0,0 +1,11 @@ +--- +title: VTGate +--- + +VTGate is a lightweight proxy server that routes traffic to the correct [VTTablet](../tablet) servers and returns consolidated results back to the client. It speaks both the MySQL Protocol and the Vitess gRPC protocol. Thus, your applications can connect to VTGate as if it is a MySQL Server. + +When routing queries to the appropriate VTTablet servers, VTGate considers the sharding scheme, required latency and the availability of tables and their underlying MySQL instances. + +**Related Vitess Documentation** + +* [Execution Plans](../execution-plans) diff --git a/content/en/docs/19.0/get-started/_index.md b/content/en/docs/19.0/get-started/_index.md new file mode 100644 index 000000000..514be5cc4 --- /dev/null +++ b/content/en/docs/19.0/get-started/_index.md @@ -0,0 +1,8 @@ +--- +title: Get Started +description: Deploy Vitess on your favorite platform +weight: 2 +aliases: ['/docs/tutorials/'] +--- + +Vitess supports binary deployment on the following platforms. See also [Build On CentOS](../../contributing/build-on-centos), [Build on MacOS](../../contributing/build-on-macos), or [Build on Ubuntu](../../contributing/build-on-ubuntu) if you are interesting in building your own binary, or contributing to Vitess. diff --git a/content/en/docs/19.0/get-started/local-brew.md b/content/en/docs/19.0/get-started/local-brew.md new file mode 100644 index 000000000..2332d7322 --- /dev/null +++ b/content/en/docs/19.0/get-started/local-brew.md @@ -0,0 +1,287 @@ +--- +title: Local Install via Homebrew +description: Instructions for using Vitess on your macOS machine for testing purposes +weight: 3 +featured: true +aliases: ['/docs/tutorials/local-brew/'] +--- + +This guide covers installing Vitess locally to macOS for testing purposes, from pre-compiled binaries. We will launch multiple copies of `mysqld`, so it is recommended to have greater than 4GB RAM, as well as 20GB of available disk space. + +A [Homebrew](https://brew.sh/) package manager is also available, which requires no dependencies on your local host. + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +> In this guide, `v9.0.0` is used in most outputs. You can replace it by the version of Vitess you are using. + +## Install Vitess with Homebrew + +Vitess supports the databases listed [here](../../overview/supported-databases/). Homebrew will install latest tagged Vitess Release. + +```bash +$ brew install vitess +Updating Homebrew... +==> Auto-updated Homebrew! +Updated 2 taps (homebrew/core and homebrew/cask). +==> Updated Formulae +Updated 19 formulae. +==> Updated Casks +Updated 1 cask. + +==> Downloading https://homebrew.bintray.com/bottles/vitess-9.0.0.catalina.bottle.tar.gz +Already downloaded: /Users/askdba/Library/Caches/Homebrew/downloads/45991b27589a191910e89a1ce529fcdaa694bb5f36b99f1b20146f8f0fc3ee6d--vitess-9.0.0.catalina.bottle.tar.gz +==> Pouring vitess-9.0.0.catalina.bottle.tar.gz +🍺 /usr/local/Cellar/vitess/9.0.0: 268 files, 528.3MB +``` +At this point Vitess binaries installed under default Homebrew install location at /usr/local/share/vitess. + +### Install Node 18.16.0+ (required to run VTAdmin) + +```bash +brew install nvm +nvm install --lts 18.16.0 +nvm use 18.16.0 +``` + +See the [vtadmin README](https://github.com/vitessio/vitess/blob/main/web/vtadmin/README.md) for more details. + +## Start a Single Keyspace Cluster + +For testing purposes initiate following example; + +```bash +$ cd /usr/local/share/vitess/examples/local/ +$ ./101_initial_cluster.sh +add /vitess/global +add /vitess/zone1 +add zone1 CellInfo +Created cell: zone1 +etcd start done... +Starting vtctld... +vtctld is running! +Successfully created keyspace commerce. Result: +{ + "name": "commerce", + "keyspace": { + "served_froms": [], + "keyspace_type": 0, + "base_keyspace": "", + "snapshot_time": null, + "durability_policy": "semi_sync", + "throttler_config": null, + "sidecar_db_name": "_vt" + } +} +Starting MySQL for tablet zone1-0000000100... +Starting vttablet for zone1-0000000100... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:51 GMT +Content-Type: text/html; charset=utf-8 + +Starting MySQL for tablet zone1-0000000101... +Starting vttablet for zone1-0000000101... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:54 GMT +Content-Type: text/html; charset=utf-8 + +Starting MySQL for tablet zone1-0000000102... +Starting vttablet for zone1-0000000102... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:56 GMT +Content-Type: text/html; charset=utf-8 + +vtorc is running! + - UI: http://localhost:16000 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtorc.out + - PID: 49556 + + +New VSchema object: +{ + "sharded": false, + "vindexes": {}, + "tables": { + "corder": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "customer": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "product": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + } + }, + "require_explicit_routing": false +} +If this is not what you expected, check the input data (as JSON parsing will skip unexpected fields). +Waiting for vtgate to be up... +vtgate is up! +Access vtgate at http://Florents-MacBook-Pro-2.local:15001/debug/status +vtadmin-api is running! + - API: http://Florents-MacBook-Pro-2.local:14200 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-api.out + - PID: 49695 + +vtadmin-web is running! + - Browser: http://Florents-MacBook-Pro-2.local:14201 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-web.out + - PID: 49698 +``` + +Verify your initial cluster: + +```sql +$ mysql -e "show vitess_tablets" ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| Cell | Keyspace | Shard | TabletType | State | Alias | Hostname | MasterTermStartTime | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| zone1 | commerce | 0 | PRIMARY | SERVING | zone1-0000000100 | localhost | 2021-02-17T13:10:13Z | +| zone1 | commerce | 0 | REPLICA | SERVING | zone1-0000000101 | localhost | | +| zone1 | commerce | 0 | RDONLY | SERVING | zone1-0000000102 | localhost | | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +``` + +You can also verify that the processes have started with `pgrep`: + +```bash +$ pgrep -fl vitess | awk '{print $2,$3}' +etcd --enable-v2=true +vtctld -topo_implementation +/bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe +/usr/local/opt/mysql@5.7/bin/mysqld --defaults-file=/usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot/vt_0000000100/my.cnf +vttablet -topo_implementation +/bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe +/usr/local/opt/mysql@5.7/bin/mysqld --defaults-file=/usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot/vt_0000000101/my.cnf +vttablet -topo_implementation +/bin/sh /usr/local/opt/mysql@5.7/bin/mysqld_safe +/usr/local/opt/mysql@5.7/bin/mysqld --defaults-file=/usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot/vt_0000000102/my.cnf +vttablet -topo_implementation +vtgate -topo_implementation +vtorc --topo_implementation +``` + +_The exact list of processes will vary. For example, you may not see `mysqld_safe` listed._ + +If you encounter any errors, such as ports already in use, you can kill the processes and start over: + +```bash +pkill -9 -f '(vtdataroot|VTDATAROOT|vitess|vtadmin)' # kill Vitess processes +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`: + +```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. + +## Connect to your cluster + +You should now be able to connect to the VTGate server that was started in `101_initial_cluster.sh`: + +```bash +/usr/local/share/vitess/examples/local> mysql +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 2 +Server version: 5.7.9-Vitess (Ubuntu) + +Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> show tables; ++-----------------------+ +| Tables_in_vt_commerce | ++-----------------------+ +| corder | +| customer | +| product | ++-----------------------+ +3 rows in set (0.00 sec) +``` + +
+ +You can also now browse and administer your new Vitess cluster using the [VTAdmin](../../reference/vtadmin/) UI at the following URL: + +```text +http://localhost:14201 +``` + +
+ +VTOrc is also setup as part of the initialization. You can look at its user-interface at: + +```text +http://localhost:16000 +``` + +## Summary + +In this example, we deployed a single unsharded keyspace named `commerce`. Unsharded keyspaces have a single shard named `0`. The following schema reflects a common ecommerce scenario that was created by the script: + +```sql +create table product ( + sku varbinary(128), + description varbinary(128), + price bigint, + primary key(sku) +); +create table customer ( + customer_id bigint not null auto_increment, + email varbinary(128), + primary key(customer_id) +); +create table corder ( + order_id bigint not null auto_increment, + customer_id bigint, + sku varbinary(128), + price bigint, + primary key(order_id) +); +``` + +The schema has been simplified to include only those fields that are significant to the example: + +* The `product` table contains the product information for all of the products. +* The `customer` table has a `customer_id` that has an `auto_increment`. A typical customer table would have a lot more columns, and sometimes additional detail tables. +* The `corder` table (named so because `order` is an SQL reserved word) has an `order_id` auto-increment column. It also has foreign keys into `customer(customer_id)` and `product(sku)`. + +## Next Steps + +You can now proceed with [MoveTables](../../user-guides/migration/move-tables). + +Or alternatively, if you would like to teardown your example: + +```bash +pkill -9 -f '(vtdataroot|VTDATAROOT)' # kill Vitess processes +rm -rf /usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot +``` diff --git a/content/en/docs/19.0/get-started/local-docker.md b/content/en/docs/19.0/get-started/local-docker.md new file mode 100644 index 000000000..d4bf43fd5 --- /dev/null +++ b/content/en/docs/19.0/get-started/local-docker.md @@ -0,0 +1,97 @@ +--- +title: Local Install via Docker +description: Instructions for using Vitess on your machine for testing purposes +weight: 5 +featured: false +aliases: ['/docs/tutorials/local-docker/'] +--- + +{{< warning >}} +This guide will only work on x86_64/amd64 based machines. +{{}} + +This guide illustrates how to run a local testing Vitess setup via Docker. The Vitess environment is identical to the [local setup](../local/), but without having to install software on one's host other than Docker. + +## Check out the vitessio/vitess repository + +Clone the GitHub repository via: + +- SSH: `git clone git@github.com:vitessio/vitess.git`, or: +- HTTP: `git clone https://github.com/vitessio/vitess.git` + +```shell +cd vitess +``` + +## Build the docker image + +In your shell, execute: + +```shell +make docker_local +``` + +This creates a docker image named `vitess/local` (aka `vitess/local:latest`) + +## Run the docker image + +In your shell, execute: + +```shell +make docker_run_local +``` + +This will set up a MySQL replication topology, as well as `etcd`, `vtctld`, `vtgate`, +`vtorc`, and `vtadmin` services. + +- `vtgate` listens on [http://127.0.0.1:15001/debug/status](http://127.0.0.1:15001/debug/status) +- `vtctld` listens on [http://127.0.0.1:15000/debug/status](http://127.0.0.1:15000/debug/status) +- `VTOrc` page is available at [http://localhost:16000](http://localhost:16000) +- `VTadmin` web application is available [http://localhost:14201](http://localhost:14201) + +From within the docker shell, aliases are set up for your convenience. Try the following `mysql` commands to connect to various tablets: + +- `mysql commerce` +- `mysql commerce@primary` +- `mysql commerce@replica` +- `mysql commerce@rdonly` + +You will find that Vitess runs a single keyspace, single shard cluster. + +## Summary + +In this example, we deployed a single unsharded keyspace named `commerce`. Unsharded keyspaces have a single shard named `0`. The following schema reflects a common ecommerce scenario that was created by the script: + +```sql +create table product ( + sku varbinary(128), + description varbinary(128), + price bigint, + primary key(sku) +); +create table customer ( + customer_id bigint not null auto_increment, + email varbinary(128), + primary key(customer_id) +); +create table corder ( + order_id bigint not null auto_increment, + customer_id bigint, + sku varbinary(128), + price bigint, + primary key(order_id) +); +``` + +The schema has been simplified to include only those fields that are significant to the example: + +* The `product` table contains the product information for all of the products. +* The `customer` table has a `customer_id` that has an `auto_increment`. A typical customer table would have a lot more columns, and sometimes additional detail tables. +* The `corder` table (named so because `order` is an SQL reserved word) has an `order_id` auto-increment column. It also has foreign keys into `customer(customer_id)` and `product(sku)`. + +## Next Steps + +You can now proceed with [MoveTables](../../user-guides/migration/move-tables). + +Exiting the docker shell terminates and destroys the vitess cluster. + diff --git a/content/en/docs/19.0/get-started/local-mac.md b/content/en/docs/19.0/get-started/local-mac.md new file mode 100644 index 000000000..4f577d74a --- /dev/null +++ b/content/en/docs/19.0/get-started/local-mac.md @@ -0,0 +1,313 @@ +--- +title: Local Install via source for Mac +description: Instructions for using Vitess on your macOS machine for testing purposes +weight: 4 +--- + +This guide covers installing Vitess locally for testing purposes, from pre-compiled binaries. We will launch multiple copies of `mysqld`, so it is recommended to have greater than 4GB RAM, as well as 20GB of available disk space. + +A pure [homebrew setup](../local-brew/) is also available. + +## Install Brew + +For the purposes of installing software you will need to have brew installed. This will also install curl and git which will also be needed: + +```sh +curl https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh > brew-install.sh + +bash brew-install.sh +``` + +## Install MySQL and etcd + +Once brew is installed you will need to install some dependencies for Vitess. Vitess supports the databases listed [here](../../overview/supported-databases/): + +```sh +brew install automake go mysql mysql-client etcd +``` + +When MySQL installs with brew it will startup, you will want to shut this process down, as Vitess will be managing the startup and shutdown of MySQL: + +```sh +$ brew services stop mysql +``` + +### Install Node 18.16.0+ (required to run VTAdmin) + +```bash +brew install nvm +nvm install --lts 18.16.0 +nvm use 18.16.0 +``` + +See the [vtadmin README](https://github.com/vitessio/vitess/blob/main/web/vtadmin/README.md) for more details. + +## PATH Settings + +With the tools you’ve just installed via brew, you will next update your PATH variable so your shell knows where to find the binaries: + +```sh +echo “export PATH=${PATH}:/opt/homebrew/opt/mysql-client/bin:/opt/homebrew/opt/mysql/bin:~/Github/vitess/bin:/Users/jason/go/bin:​​/opt/homebrew/bin” >> ~/.zshrc +source ~/.zshrc +``` + +If you’re using bash for your shell you’ll have to update the paths in `.bash_profile` or `.bashrc` instead. Mac does not read `.bashrc` by default: + +```sh +$ echo “export PATH=${PATH}:/opt/homebrew/opt/mysql-client/bin:/opt/homebrew/opt/mysql/bin:~/Github/vitess/bin:/Users/jason/go/bin:/opt/homebrew/bin” >> ~/.bash_profile +$ source ~/.bash_profile +``` + +## System Check + +Before going further, you should check to confirm your shell has access to `go`, `mysql`, and `mysqld`. If versions are not returned when you run the following commands you should check that the programs are installed and the path is correct for your shell: + +```sh +$ mysqld --version +$ mysql --version +$ go version +$ etcd --version +$ node --version +$ npm --version +``` + +## Install Vitess + +With everything now in place you can clone and build Vitess. + +```sh +$ git clone https://github.com/vitessio/vitess.git +$ cd vitess +$ make build +``` + +It will take some time for Vitess to build. Once it completes you should see a bin folder which will hold the Vitess binaries. You will need to add this folder to your `PATH` variable as well: + +```sh +$ cd bin +$ echo "$(printf 'export PATH="${PATH}:'; echo "$(pwd)\"")" >> ~/.zshrc +$ source ~/.zshrc +``` + +If you are using bash this will need to be your `.bash_profile` or `.bashrc` file instead: + +```sh +$ cd bin +$ echo "$(printf 'export PATH="${PATH}:'; echo "$(pwd)\"")" >> ~/.bash_profile +$ source ~/.bash_profile +``` + +You are now ready to start your first cluster! Open a new terminal window to ensure your `.bashrc` file changes take effect. + +## Start a Single Keyspace Cluster + +You are now ready to stand up your first Vitess cluster, using the example scripts provided in the source code. Assuming you are still in the bin directory you will need to navigate to the sample files: + +```sh +$ cd ../examples/local/ +``` + +From here you can startup the cluster and source the env file which will help set environment variables used when working with this local cluster: + +```sh +$ ./101_initial_cluster.sh +$ source ../common/env.sh +``` + +You should see an output similar to the following: + +```bash +$ ./101_initial_cluster.sh +$ ./101_initial_cluster.sh +add /vitess/global +add /vitess/zone1 +add zone1 CellInfo +Created cell: zone1 +etcd start done... +Starting vtctld... +vtctld is running! +Successfully created keyspace commerce. Result: +{ + "name": "commerce", + "keyspace": { + "served_froms": [], + "keyspace_type": 0, + "base_keyspace": "", + "snapshot_time": null, + "durability_policy": "semi_sync", + "throttler_config": null, + "sidecar_db_name": "_vt" + } +} +Starting MySQL for tablet zone1-0000000100... +Starting vttablet for zone1-0000000100... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:51 GMT +Content-Type: text/html; charset=utf-8 + +Starting MySQL for tablet zone1-0000000101... +Starting vttablet for zone1-0000000101... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:54 GMT +Content-Type: text/html; charset=utf-8 + +Starting MySQL for tablet zone1-0000000102... +Starting vttablet for zone1-0000000102... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:56 GMT +Content-Type: text/html; charset=utf-8 + +vtorc is running! + - UI: http://localhost:16000 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtorc.out + - PID: 49556 + + +New VSchema object: +{ + "sharded": false, + "vindexes": {}, + "tables": { + "corder": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "customer": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "product": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + } + }, + "require_explicit_routing": false +} +If this is not what you expected, check the input data (as JSON parsing will skip unexpected fields). +Waiting for vtgate to be up... +vtgate is up! +Access vtgate at http://Florents-MacBook-Pro-2.local:15001/debug/status +vtadmin-api is running! + - API: http://Florents-MacBook-Pro-2.local:14200 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-api.out + - PID: 49695 + +vtadmin-web is running! + - Browser: http://Florents-MacBook-Pro-2.local:14201 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-web.out + - PID: 49698 +``` + +If you encounter any errors, such as ports already in use, you can kill the processes and start over. Ensure you're in the vitess/examples/local directory, then issue the statement to kill the processes and remove the data directory. +This data directory `vtdataroot` will get recreated when you run the 101_initial_cluster.sh startup script again. + +```sh +user@computer:~/Github/vitess/examples/local$ pwd +/home/user/Github/vitess/examples/local + +user@computer:~/Github/vitess/examples/local$ pkill -9 -f '(vtdataroot|VTDATAROOT|vitess|vtadmin)' +etcd killed (pid 224091) +vtctld killed (pid 224154) +mysqld_safe killed (pid 224247) +mysqld killed (pid 224716) +vttablet killed (pid 224764) +mysqld_safe killed (pid 224897) +mysqld killed (pid 225364) +vttablet killed (pid 225413) +mysqld_safe killed (pid 225529) +mysqld killed (pid 225995) +vttablet killed (pid 226045) +vtgate killed (pid 226204) +vtadmin killed (pid 226391) +vtorc killed (pid 226397) + +user@computer:~/Github/vitess/examples/local$ rm -rf ./vtdataroot +``` + +## Connect to your cluster + +You should now be able to connect to the VTGate server that was started in `101_initial_cluster.sh`: + +```sh +$ mysql -P 15306 -u root --protocol tcp +``` + +
+ +You can also now browse and administer your new Vitess cluster using the [VTAdmin](../../reference/vtadmin/) UI at the following URL: + +```text +http://localhost:14201 +``` + +
+ +VTOrc is also setup as part of the initialization. You can look at its user-interface at: + +```text +http://localhost:16000 +``` + +## Summary + +In this example, we deployed a single unsharded keyspace named `commerce`. Unsharded keyspaces have a single shard named `0`. The following schema reflects a common ecommerce scenario that was created by the script: + +```sql +create table product ( + sku varbinary(128), + description varbinary(128), + price bigint, + primary key(sku) +); +create table customer ( + customer_id bigint not null auto_increment, + email varbinary(128), + primary key(customer_id) +); +create table corder ( + order_id bigint not null auto_increment, + customer_id bigint, + sku varbinary(128), + price bigint, + primary key(order_id) +); +``` + +The schema has been simplified to include only those fields that are significant to the example: + +* The `product` table contains the product information for all of the products. +* The `customer` table has a `customer_id` that has an `auto_increment`. A typical customer table would have a lot more columns, and sometimes additional detail tables. +* The `corder` table (named so because `order` is an SQL reserved word) has an `order_id` auto-increment column. It also has foreign keys into `customer(customer_id)` and `product(sku)`. + +## Next Steps + +You can now proceed with [MoveTables](../../user-guides/migration/move-tables). + +Or alternatively, once you are finished with the local examples or if you would like to start over, you can clean up by running the 401_teardown script: + +```sh +$ ./401_teardown.sh +$ rm -rf ./vtdataroot +``` + +Sometimes you will still need to manually kill processes if there are errors in the environment: + +```sh +$ pkill -9 -f ./vtdataroot +$ rm -rf ./vtdataroot +``` diff --git a/content/en/docs/19.0/get-started/local.md b/content/en/docs/19.0/get-started/local.md new file mode 100644 index 000000000..1667580df --- /dev/null +++ b/content/en/docs/19.0/get-started/local.md @@ -0,0 +1,318 @@ +--- +title: Local Install +description: Instructions for using Vitess on your machine for testing purposes +weight: 2 +featured: true +aliases: ['/docs/tutorials/local/'] +--- + +This guide covers installing Vitess locally for testing purposes, from pre-compiled binaries. We will launch multiple copies of `mysqld`, so it is recommended to have greater than 4GB RAM, as well as 20GB of available disk space. + +A [docker setup](../local-docker/) is also available, which requires no dependencies on your local host. + +## Install MySQL and etcd + +Vitess supports the databases listed [here](../../overview/supported-databases/). We recommend MySQL 8.0 if your installation method provides that option: + +```sh +# Ubuntu based +sudo apt install -y mysql-server etcd curl + +# Debian +sudo apt install -y default-mysql-server default-mysql-client etcd curl + +# Yum based +sudo yum -y localinstall https://dev.mysql.com/get/mysql80-community-release-el8-3.noarch.rpm +sudo yum -y install mysql-community-server etcd curl +``` + +On apt-based distributions the services `mysqld` and `etcd` will need to be shutdown, since `etcd` will conflict with the `etcd` started in the examples, and `mysqlctl` will start its own copies of `mysqld`: + +```sh +# Debian and Ubuntu +sudo service mysql stop +sudo service etcd stop +sudo systemctl disable mysql +sudo systemctl disable etcd +``` + +## Disable AppArmor or SELinux + +AppArmor/SELinux will not allow Vitess to launch MySQL in any data directory by default. You will need to disable it: + +__AppArmor__: +```sh +# Debian and Ubuntu +sudo ln -s /etc/apparmor.d/usr.sbin.mysqld /etc/apparmor.d/disable/ +sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld + +# The following command should return an empty result: +sudo aa-status | grep mysqld +``` + +__SELinux__: +```sh +# CentOS +sudo setenforce 0 +``` + +## Install Vitess + +Download the [latest binary release](https://github.com/vitessio/vitess/releases) for Vitess on Linux. For example with Vitess 17: + +**Notes:** + +* 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 +file=vitess-${version}-70a9466.tar.gz +wget https://github.com/vitessio/vitess/releases/download/v${version}/${file} +tar -xzf ${file} +cd ${file/.tar.gz/} +sudo mkdir -p /usr/local/vitess +sudo cp -r * /usr/local/vitess/ +``` + +Make sure to add `/usr/local/vitess/bin` to the `PATH` environment variable. You can do this by adding the following to your `$HOME/.bashrc` file: + +```sh +export PATH=/usr/local/vitess/bin:${PATH} +``` + +You are now ready to start your first cluster! Open a new terminal window to ensure your `.bashrc` file changes take effect. + +## Start a Single Keyspace Cluster + +Start by copying the local examples included with Vitess to your preferred location. For our first example we will deploy a [single unsharded keyspace](../../concepts/keyspace). The file `101_initial_cluster.sh` is for example `1` phase `01`. Lets execute it now: + +```sh +vitess_path=/usr/local/vitess +mkdir ~/my-vitess-example +cp -r ${vitess_path}/{examples,web} ~/my-vitess-example +cd ~/my-vitess-example/examples/local +./101_initial_cluster.sh +``` + +You should see an output similar to the following: + +```bash +$ ./101_initial_cluster.sh +add /vitess/global +add /vitess/zone1 +add zone1 CellInfo +Created cell: zone1 +etcd start done... +Starting vtctld... +vtctld is running! +Successfully created keyspace commerce. Result: +{ + "name": "commerce", + "keyspace": { + "served_froms": [], + "keyspace_type": 0, + "base_keyspace": "", + "snapshot_time": null, + "durability_policy": "semi_sync", + "throttler_config": null, + "sidecar_db_name": "_vt" + } +} +Starting MySQL for tablet zone1-0000000100... +Starting vttablet for zone1-0000000100... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:51 GMT +Content-Type: text/html; charset=utf-8 + +Starting MySQL for tablet zone1-0000000101... +Starting vttablet for zone1-0000000101... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:54 GMT +Content-Type: text/html; charset=utf-8 + +Starting MySQL for tablet zone1-0000000102... +Starting vttablet for zone1-0000000102... +HTTP/1.1 200 OK +Date: Mon, 26 Jun 2023 19:21:56 GMT +Content-Type: text/html; charset=utf-8 + +vtorc is running! + - UI: http://localhost:16000 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtorc.out + - PID: 49556 + + +New VSchema object: +{ + "sharded": false, + "vindexes": {}, + "tables": { + "corder": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "customer": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "product": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + } + }, + "require_explicit_routing": false +} +If this is not what you expected, check the input data (as JSON parsing will skip unexpected fields). +Waiting for vtgate to be up... +vtgate is up! +Access vtgate at http://Florents-MacBook-Pro-2.local:15001/debug/status +vtadmin-api is running! + - API: http://Florents-MacBook-Pro-2.local:14200 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-api.out + - PID: 49695 + +vtadmin-web is running! + - Browser: http://Florents-MacBook-Pro-2.local:14201 + - Logs: /Users/florentpoinsard/Code/vitess/vtdataroot/tmp/vtadmin-web.out + - PID: 49698 +``` + +You can also verify that the processes have started with `pgrep`: + +```bash +$ pgrep -fl vitess +14119 etcd +14176 vtctld +14251 mysqld_safe +14720 mysqld +14787 vttablet +14885 mysqld_safe +15352 mysqld +15396 vttablet +15492 mysqld_safe +15959 mysqld +16006 vttablet +16112 vtgate +16788 vtorc +``` + +_The exact list of processes will vary. For example, you may not see `mysqld_safe` listed._ + +If you encounter any errors, such as ports already in use, you can kill the processes and start over: + +```sh +pkill -9 -f '(vtdataroot|VTDATAROOT|vitess|vtadmin)' # kill Vitess processes +rm -rf vtdataroot +``` + +## Setup Aliases + +For ease-of-use, Vitess provides aliases for `mysql`, `vtctlclient` 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. + +## Connect to your cluster + +You should now be able to connect to the VTGate server that was started in `101_initial_cluster.sh`: + +```bash +$ mysql +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 2 +Server version: 8.0.31-Vitess (Ubuntu) + +Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> show tables; ++-----------------------+ +| Tables_in_vt_commerce | ++-----------------------+ +| corder | +| customer | +| product | ++-----------------------+ +3 rows in set (0.00 sec) +``` + +
+ +You can also now browse and administer your new Vitess cluster using the [VTAdmin](../../reference/vtadmin/) UI at the following URL: + +```text +http://localhost:14201 +``` + +
+ +VTOrc is also setup as part of the initialization. You can look at its user-interface at: + +```text +http://localhost:16000 +``` + +## Summary + +In this example, we deployed a single unsharded keyspace named `commerce`. Unsharded keyspaces have a single shard named `0`. The following schema reflects a common ecommerce scenario that was created by the script: + +```sql +create table product ( + sku varbinary(128), + description varbinary(128), + price bigint, + primary key(sku) +); +create table customer ( + customer_id bigint not null auto_increment, + email varbinary(128), + primary key(customer_id) +); +create table corder ( + order_id bigint not null auto_increment, + customer_id bigint, + sku varbinary(128), + price bigint, + primary key(order_id) +); +``` + +The schema has been simplified to include only those fields that are significant to the example: + +* The `product` table contains the product information for all of the products. +* The `customer` table has a `customer_id` that has an `auto_increment`. A typical customer table would have a lot more columns, and sometimes additional detail tables. +* The `corder` table (named so because `order` is an SQL reserved word) has an `order_id` auto-increment column. It also has foreign keys into `customer(customer_id)` and `product(sku)`. + +## Next Steps + +You can now proceed with [MoveTables](../../user-guides/migration/move-tables). + +Or alternatively, if you would like to teardown your example: + +```bash +./401_teardown.sh +rm -rf vtdataroot +``` diff --git a/content/en/docs/19.0/get-started/operator.md b/content/en/docs/19.0/get-started/operator.md new file mode 100644 index 000000000..55112f490 --- /dev/null +++ b/content/en/docs/19.0/get-started/operator.md @@ -0,0 +1,164 @@ +--- +title: Vitess Operator for Kubernetes +weight: 1 +featured: true +aliases: ['/docs/tutorials/kubernetes/','/user-guide/sharding-kubernetes.html', '/docs/get-started/scaleway/','/docs/get-started/kubernetes/'] +--- + +PlanetScale provides a [Vitess Operator for Kubernetes](https://github.com/planetscale/vitess-operator), released under the Apache 2.0 license. The following steps show how to get started using Minikube: + +## Prerequisites + +{{}}Information on the versions of Kubernetes supported can be [found here](https://github.com/planetscale/vitess-operator#compatibility).{{}} + +Before we get started, let’s get a few pre-requisites out of the way: + +1. Install [Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) and start a Minikube engine: + ```bash + minikube start --kubernetes-version=v1.25.8 --cpus=4 --memory=11000 --disk-size=32g + ``` + +2. Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) and ensure it is in your `PATH`. + +1. Install [the MySQL client](https://dev.mysql.com/doc/mysql-getting-started/en/) locally. + +1. Install [vtctldclient](https://vitess.io/docs/get-started/local/#install-vitess) locally. + +## Install the Operator + +Change to the operator example directory: + +```bash +git clone https://github.com/vitessio/vitess +cd vitess/examples/operator +``` + +Install the operator: + +```bash +kubectl apply -f operator.yaml +``` + +## Bring up an initial cluster + +In this directory, you will see a group of yaml files. The first digit of each file name indicates the phase of example. The next two digits indicate the order in which to execute them. For example, `101_initial_cluster.yaml` is the first file of the first phase. We shall execute that now: + +```bash +kubectl apply -f 101_initial_cluster.yaml +``` + +### Verify cluster + +You can check the state of your cluster with `kubectl get pods`. After a few minutes, it should show that all pods are in the status of running: + +```bash +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +example-commerce-x-x-zone1-vtorc-c13ef6ff-5db4c77865-l96xq 1/1 Running 2 (2m49s ago) 5m16s +example-etcd-faf13de3-1 1/1 Running 0 5m17s +example-etcd-faf13de3-2 1/1 Running 0 5m17s +example-etcd-faf13de3-3 1/1 Running 0 5m17s +example-vttablet-zone1-2469782763-bfadd780 3/3 Running 1 (2m43s ago) 5m16s +example-vttablet-zone1-2548885007-46a852d0 3/3 Running 1 (2m47s ago) 5m16s +example-zone1-vtadmin-c03d7eae-7c6f6c98f8-f4f5z 2/2 Running 0 5m17s +example-zone1-vtctld-1d4dcad0-57b9d7bc4b-2tnqd 1/1 Running 2 (2m53s ago) 5m17s +example-zone1-vtgate-bc6cde92-7d445d676-x6npk 1/1 Running 2 (3m ago) 5m17s +vitess-operator-5f47c6c45d-bgqp2 1/1 Running 0 6m52s +``` + +## Setup Port-forward + +{{< warning >}} +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`: + +```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. + +Once the port-forward starts running, the VTAdmin UI will be available at [http://localhost:14000/](http://localhost:14000/) + +## Create Schema + +Load our initial schema: + +```bash +vtctldclient ApplySchema --sql-file="create_commerce_schema.sql" commerce +vtctldclient ApplyVSchema --vschema-file="vschema_commerce_initial.json" commerce +``` + +### Connect to your cluster + +You should now be able to connect to the VTGate Server in your cluster with the MySQL client: + +```text +~/vitess/examples/operator$ mysql +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 3 +Server version: 5.7.9-Vitess MySQL Community Server (GPL) + +Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> show databases; ++-----------+ +| Databases | ++-----------+ +| commerce | ++-----------+ +1 row in set (0.00 sec) +``` + +### Summary + +In this example, we deployed a single unsharded keyspace named `commerce`. Unsharded keyspaces have a single shard named `0`. The following schema reflects a common ecommerce scenario that was created by the script: + +``` sql +create table product( + sku varbinary(128), + description varbinary(128), + price bigint, + primary key(sku) +); +create table customer( + customer_id bigint not null auto_increment, + email varbinary(128), + primary key(customer_id) +); +create table corder( + order_id bigint not null auto_increment, + customer_id bigint, + sku varbinary(128), + price bigint, + primary key(order_id) +); +``` + +The schema has been simplified to include only those fields that are significant to the example: + +* The `product` table contains the product information for all of the products. +* The `customer` table has a `customer_id` that has an `auto_increment`. A typical customer table would have a lot more columns, and sometimes additional detail tables. +* The `corder` table (named so because `order` is an SQL reserved word) has an `order_id` auto-increment column. It also has foreign keys into `customer(customer_id)` and `product(sku)`. + +## Next Steps + +You can now proceed with [MoveTables](../../user-guides/migration/move-tables). + +Or alternatively, if you would like to teardown your example: + +```sh +kubectl delete -f 101_initial_cluster.yaml +``` +Congratulations on completing this exercise! diff --git a/content/en/docs/19.0/get-started/vttestserver-docker-image.md b/content/en/docs/19.0/get-started/vttestserver-docker-image.md new file mode 100644 index 000000000..e64739f6a --- /dev/null +++ b/content/en/docs/19.0/get-started/vttestserver-docker-image.md @@ -0,0 +1,128 @@ +--- +title: Vttestserver Docker Image +weight: 10 +featured: true +aliases: ['/docs/tutorials/vttestserver/'] +--- + +This guide covers using the vttestserver docker image for testing purposes. This is also the docker image that we use for testing in [Vitess Framework Testing](https://github.com/planetscale/vitess-framework-testing). + +## Get the docker image + +The first step is to get the docker image. There are two ways of doing this : + +### 1. From the vitessio/vitess repository + +#### Check out the vitessio/vitess repository + +Clone the GitHub repository via: + +- SSH: `git clone git@github.com:vitessio/vitess.git`, or: +- HTTP: `git clone https://github.com/vitessio/vitess.git` + +```shell +cd vitess +``` + +#### Build the docker image + +In your shell, execute: + +```shell +make docker_vttestserver +``` + +This creates 2 docker images named `vitess/vttestserver:mysql57` and `vitess/vttestserver:mysql80` + +### 2. Pulling from docker hub + +Alternately, you can get the latest docker images from the docker hub. In your shell, execute: + +```shell +docker pull vitess/vttestserver:mysql57 +docker pull vitess/vttestserver:mysql80 +``` + +## Run the docker image + +At this point, you should have a docker image named `vitess/vttestserver:mysql57` or `vitess/vttestserver:mysql80`. + +### Environment variables + +The docker image expects some of the environment variables to be set to function properly. The following table lists all the environment variables available along with their usages. + +| Environment variable | Required | Use | +|---------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| *KEYSPACES* | yes | Specifies the names of the keyspaces to be created as a comma separated value. | +| *NUM_SHARDS* | yes | Specifies the number of shards in each keyspace. It is a comma separated value as well, read in conjunction with the KEYSPACES. | +| *PORT* | yes | The starting of the port addresses that vitess will use to register its components like vtgate, etc. | +| *MYSQL_MAX_CONNECTIONS* | no | Maximum number of connections that the MySQL instance will support. If unspecified, it defaults to 1000. | +| *MYSQL_BIND_HOST* | no | Which host to bind the MySQL listener to. If unspecified, it defaults to `127.0.0.1`. | +| *MYSQL_SERVER_VERSION* | no | MySQL server version to advertise. If unspecified, it defaults to `8.0.31-vitess` or `5.7.9-vitess` according to the version of vttestserver run. | +| *CHARSET* | no | Default charset to use. If unspecified, it defaults to `utf8mb4`. | +| *FOREIGN_KEY_MODE* | no | This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow (default), disallow. | +| *ENABLE_ONLINE_DDL* | no | Allow users to submit, review and control Online DDL. Valid values are: true (default), false. | +| *ENABLE_DIRECT_DDL* | no | Allow users to submit direct DDL statements. Valid values are: true (default), false. | +| *PLANNER_VERSION* | no | Sets the default planner to use when the session has not changed it. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right. | +| *TABLET_REFRESH_INTERVAL* | no | Interval at which vtgate refreshes tablet information from topology server. | + +Environment variables in docker can be specified using the `-e` aka `--env` flag. + +### Sending queries to vttestserver container from outside + +The vtgate listens for MySQL connections on 3 + the `PORT` environment variable specified. i.e. if you specify `PORT` to be 33574, then vtgate will be listening to connections on 33577, on the `MYSQL_BIND_HOST` which defaults to localhost. But this port will be on the docker container side. To connect to vtgate externally from a MySQL client, you will need to publish that port as well and specify the `MYSQL_BIND_HOST` to `0.0.0.0`. This can be done via the `-p` aka `--publish` flag to docker. For eg: adding `-p 33577:33577` to the `docker +run` command will publish the container's 33577 port to your local 33577 port, which can now be used to connect to the vtgate. + +### Persisting container data + +If you wish to keep the state of the test container across reboots, such as when running the vttestserver container as a database container in local application development environments, you may optionally pass the `--persistent_mode` flag, along with a `--data_dir` directory which is bound to a docker volume. Due to a bug, the `--port` argument must also be present for correct operation. + +When running in this mode, underlying MySQL table schemas, their data, and the Vitess VSchema objects are persisted under the provided `--data_dir`. + +For example: + +```shell +docker run --name=vttestserver \ + -p 33577:33577 \ + --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \ + --health-interval=5s \ + --health-timeout=2s \ + --health-retries=5 \ + -v vttestserver_data:/vt/vtdataroot/vitess \ + vitess/vttestserver:mysql80 + /vt/bin/vttestserver \ + --alsologtostderr \ + --data_dir=/vt/vtdataroot/vitess \ + --persistent_mode \ + --port=33574 \ + --mysql_bind_host=0.0.0.0 \ + --keyspaces=test,unsharded \ + --num_shards=2,1 +``` + +## Example + +An example command to run the docker image is as follows : + +```shell +docker run --name=vttestserver \ + -p 33577:33577 \ + -e PORT=33574 \ + -e KEYSPACES=test,unsharded \ + -e NUM_SHARDS=2,1 \ + -e MYSQL_MAX_CONNECTIONS=70000 \ + -e MYSQL_BIND_HOST=0.0.0.0 \ + --health-cmd="mysqladmin ping -h127.0.0.1 -P33577" \ + --health-interval=5s \ + --health-timeout=2s \ + --health-retries=5 \ + vitess/vttestserver:mysql80 +``` + +Now, we can connect to the vtgate from a MySQL client as follows : + +```shell +mysql --host 127.0.0.1 --port 33577 --user "root" +``` + +We have 2 keyspaces which we can use, `test` which has 2 shards and `unsharded` which has a single shard. diff --git a/content/en/docs/19.0/overview/_index.md b/content/en/docs/19.0/overview/_index.md new file mode 100644 index 000000000..7b7450ff5 --- /dev/null +++ b/content/en/docs/19.0/overview/_index.md @@ -0,0 +1,8 @@ +--- +title: Overview +description: High-level information about Vitess +weight: 1 +aliases: ['/docs/overview/scalingwithvitess/','/user-guide/introduction.html'] +--- + +The Vitess overview documentation provides general information about Vitess that's less immediately practical than what you'll find in [Get Started](../get-started) section and the [User Guides](../user-guides). diff --git a/content/en/docs/19.0/overview/architecture.md b/content/en/docs/19.0/overview/architecture.md new file mode 100644 index 000000000..b94d7e5d4 --- /dev/null +++ b/content/en/docs/19.0/overview/architecture.md @@ -0,0 +1,17 @@ +--- +title: Architecture +weight: 2 +featured: true +--- + +The Vitess platform consists of a number of server processes, command-line utilities, and web-based utilities, backed by a consistent metadata store. + +Depending on the current state of your application, you could arrive at a full Vitess implementation through a number of different process flows. For example, if you're building a service from scratch, your first step with Vitess would be to define your database topology. However, if you need to scale your existing database, you'd likely start by deploying Vitess in Unmanaged mode. + +Vitess tools and servers are designed to help you whether you start with a complete fleet of databases or start small and scale over time. For smaller implementations, vttablet features like connection pooling and query rewriting help you get more from your existing hardware. Vitess' automation tools then provide additional benefits for larger implementations. + +The diagram below illustrates Vitess' components: + +Architecture Diagram + +For additional details on each of the components, see [Concepts](../../concepts). diff --git a/content/en/docs/19.0/overview/cloud-native.md b/content/en/docs/19.0/overview/cloud-native.md new file mode 100644 index 000000000..7baea63e1 --- /dev/null +++ b/content/en/docs/19.0/overview/cloud-native.md @@ -0,0 +1,19 @@ +--- +title: Cloud Native +weight: 4 +--- + +Vitess is well-suited for Cloud deployments because it enables databases to incrementally add capacity. The easiest way to run Vitess in the Cloud is via Kubernetes. + +## Vitess on Kubernetes + +Kubernetes is an open-source orchestration system for containerized applications, and Vitess can run as a Kubernetes-aware cloud native distributed database. + +Kubernetes handles scheduling onto nodes in a compute cluster, actively manages workloads on those nodes, and groups containers comprising an application for easy management and discovery. This provides an analogous open-source environment to the way Vitess ran in YouTube on Borg, the predecessor to Kubernetes. + +An open-source Kubernetes [operator](https://github.com/planetscale/vitess-operator) is available for Vitess, and is being used in production by several deployments. + +**Related Vitess Documentation** + +* [Kubernetes Quickstart](../../get-started/operator/) + diff --git a/content/en/docs/19.0/overview/history.md b/content/en/docs/19.0/overview/history.md new file mode 100644 index 000000000..b91d4b3e5 --- /dev/null +++ b/content/en/docs/19.0/overview/history.md @@ -0,0 +1,19 @@ +--- +title: History +description: Born at YouTube, released as Open Source +weight: 5 +--- + +Vitess was created in 2010 to solve the MySQL scalability challenges that the team at YouTube faced. This section briefly summarizes the sequence of events that led to Vitess' creation: + +1. YouTube's MySQL database reached a point when peak traffic would soon exceed the database's serving capacity. To temporarily alleviate the problem, YouTube created a master database for write traffic and a replica database for read traffic. +2. With demand for cat videos at an all-time high, read-only traffic was still high enough to overload the replica database. So YouTube added more replicas, again providing a temporary solution. +3. Eventually, write traffic became too high for the master database to handle, requiring YouTube to shard data to handle incoming traffic. As an aside, sharding would have also become necessary if the overall size of the database became too large for a single MySQL instance. +4. YouTube's application layer was modified so that before executing any database operation, the code could identify the right database shard to receive that particular query. + +Vitess let YouTube remove that logic from the application source code, introducing a proxy between the application and the database to route and manage database interactions. Since then, YouTube has scaled its user base by a factor of more than 50, greatly increasing its capacity to serve pages, process newly uploaded videos, and more. Even more importantly, Vitess is a platform that continues to scale. + +## Vitess becomes a CNCF project + +The [CNCF](https://www.cncf.io) serves as the vendor-neutral home for many of the fastest-growing open source projects. In [February 2018](https://www.cncf.io/blog/2018/02/05/cncf-host-vitess/) the Technical Oversight Committee (TOC) voted to accept Vitess as a CNCF incubation project. Vitess became the eighth CNCF project to graduate in [November 2019](https://www.cncf.io/announcement/2019/11/05/cloud-native-computing-foundation-announces-vitess-graduation/), joining Kubernetes, Prometheus, Envoy, CoreDNS, containerd, Fluentd, and Jaeger. + diff --git a/content/en/docs/19.0/overview/img/architecture.svg b/content/en/docs/19.0/overview/img/architecture.svg new file mode 100644 index 000000000..f5fecc21c --- /dev/null +++ b/content/en/docs/19.0/overview/img/architecture.svg @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/content/en/docs/19.0/overview/scalability-philosophy.md b/content/en/docs/19.0/overview/scalability-philosophy.md new file mode 100644 index 000000000..ee261ac79 --- /dev/null +++ b/content/en/docs/19.0/overview/scalability-philosophy.md @@ -0,0 +1,75 @@ +--- +title: Scalability Philosophy +weight: 3 +aliases: ['/docs/launching/scalability-philosophy/'] +--- + +Scalability problems can be solved using many approaches. This document describes Vitess' approach to address these problems. + +## Small instances + +When deciding to shard or break databases up into smaller parts, it's tempting to break them just enough that they fit in one machine. In the industry, it’s common to run only one MySQL instance per host. + +Vitess recommends that instances be broken up into manageable chunks (250GB per MySQL server), and not to shy away from running multiple instances per host. The net resource usage would be about the same. But the manageability greatly improves when MySQL instances are small. There is the complication of keeping track of ports, and separating the paths for the MySQL instances. However, everything else becomes simpler once this hurdle is crossed. + +There are fewer lock contentions to worry about, replication is a lot happier, production impact of outages is smaller, backups and restores run faster, and a lot more secondary advantages can be realized. For example, you can shuffle instances around to get better machine or rack diversity leading to even smaller production impact on outages, and improved resource usage. + +## Durability through replication + +Traditional data storage software treated data as durable as soon as it was flushed to disk. However, this approach is impractical in today’s world of commodity hardware. Such an approach also does not address disaster scenarios. + +The new approach to durability is achieved by copying the data to multiple machines, and even geographical locations. This form of durability addresses the modern concerns of device failures and disasters. + +Many of the workflows in Vitess have been built with this approach in mind. For example, turning on semi-sync replication is highly recommended. This allows Vitess to failover to a new replica when a primary goes down, with no data loss. Vitess also recommends that you avoid recovering a crashed database. Instead, create a fresh one from a recent backup and let it catch up. + +Relying on replication also allows you to loosen some of the disk-based durability settings. For example, you can turn off `sync_binlog`, which greatly reduces the number of IOPS to the disk thereby increasing effective throughput. + +## Consistency model + +Before sharding or moving tables to different keyspaces, the application needs to be verified (or changed) such that it can tolerate the following changes: + +* Cross-shard reads may not be consistent with each other. Conversely, the sharding decision should also attempt to minimize such occurrences because cross-shard reads are more expensive. +* In "best-effort mode", cross-shard transactions can fail in the middle and result in partial commits. You could instead use "2PC mode" transactions that give you distributed atomic guarantees. However, choosing this option increases the write cost by approximately 50%. + +Single shard transactions continue to remain ACID, just like MySQL supports it. + +If there are read-only code paths that can tolerate slightly stale data, the queries should be sent to REPLICA tablets for OLTP, and RDONLY tablets for OLAP workloads. This allows you to scale your read traffic more easily, and gives you the ability to distribute them geographically. + +This trade-off allows for better throughput at the expense of stale or possibly inconsistent reads, since the reads may be lagging behind the primary, as data changes (and possibly with varying lag on different shards). To mitigate this, VTGate servers are capable of monitoring replica lag and can be configured to avoid serving data from instances that are lagging beyond X seconds. + +For a true snapshot, queries must be sent to the primary within a transaction. For read-after-write consistency, reading from the primary without a transaction is sufficient. + +To summarize, these are the various levels of consistency supported: + +* `REPLICA/RDONLY` read: Servers can be scaled geographically. Local reads are fast, but can be stale depending on replica lag. +* `PRIMARY` read: There is only one worldwide primary per shard. Reads coming from remote locations will be subject to network latency and reliability, but the data will be up-to-date (read-after-write consistency). The isolation level is `READ_COMMITTED`. +* `PRIMARY` transactions: These exhibit the same properties as PRIMARY reads. However, you get REPEATABLE_READ consistency and ACID writes for a single shard. Support is planned for cross-shard Atomic transactions. + +As for atomicity, the following levels are supported: + +* `SINGLE`: disallow multi-db transactions. +* `MULTI`: multi-db transactions with best effort commit. +* `TWOPC`: multi-db transactions with 2PC commit. + +### No active-active replication + +Vitess doesn’t support active-active replication setup (previously called multi-master). It has alternate ways of addressing most of the use cases that are typically solved by such a configuration. + +* Scalability: There are situations where active-active gives you a little bit of additional runway. However, since all writes have to eventually be applied to all writable servers, it’s not a sustainable strategy. Vitess addresses this problem through sharding, which can scale indefinitely. +* High availability: Vitess has native capability for detecting primary failures and performing a failover to a new primary within seconds of failure detection. This is usually sufficient for most applications. +* Low-latency geographically distributed writes: This is one case that is not addressed by Vitess. The current recommendation is to absorb the latency cost of long-distance round-trips for writes. If the data distribution allows, you still have the option of sharding based on geographic affinity. You can then setup primaries for different shards to be in different geographic locations. This way, most of the primary writes can still be local. + +## Multi-cell + +Vitess is meant to run in multiple data centers / regions / cells. In this part, we'll use "cell" to mean a set of servers that are very close together, and share the same regional availability. + +A cell typically contains a set of tablets, a vtgate pool, and app servers that use the Vitess cluster. With Vitess, all components can be configured and brought up as needed: + +* The primary for a shard can be in any cell. If cross-cell primary access is required, vtgate can be configured to do so easily (by passing the cell that contains the primary as a cell to watch). +* It is not uncommon to have the cells that can contain the primary be more provisioned than read-only serving cells. These *primary-capable* cells may need one more replica to handle a possible failover, while still maintaining the same replica serving capacity. +* Failing over from a primary in one cell to a primary in a different cell is no different than a local failover. It has an implication on traffic and latency, but if the application traffic also gets re-directed to the new cell, the end result is stable. +* It is also possible to have some shards with a primary in one cell, and some other shards with their primary in another cell. vtgate will just route the traffic to the right place, incurring extra latency cost only on the remote access. For instance, creating U.S. user records in a database with primaries in the U.S. and European user records in a database with primaries in Europe is easy to do. Replicas can exist in every cell anyway, and serve the replica traffic quickly. +* Replica serving cells are a good compromise to reduce user-visible latency: they only contain replica servers, and primary access is always done remotely. If the application profile is mostly reads, this works really well. +* Not all cells need `rdonly` (or batch) instances. Only the cells that run batch jobs, or OLAP jobs, really need them. + +Note that Vitess uses local-cell data first, and is very resilient to any cell going down (most of our processes handle that case gracefully). diff --git a/content/en/docs/19.0/overview/supported-databases.md b/content/en/docs/19.0/overview/supported-databases.md new file mode 100644 index 000000000..6aaa5db56 --- /dev/null +++ b/content/en/docs/19.0/overview/supported-databases.md @@ -0,0 +1,19 @@ +--- +title: Supported Databases +weight: 2 +featured: true +--- + +Vitess deploys, scales and manages clusters of open-source SQL database instances. Currently, Vitess supports the [MySQL](https://www.mysql.com/) and [Percona Server for MySQL](https://www.percona.com/software/mysql-database/percona-server) databases. + +The [VTGate](../../concepts/vtgate/) proxy server advertises its version as MySQL 8.0. + +## MySQL versions 5.7 to 8.0 + +Vitess supports the core features of MySQL versions 5.7 to 8.0, with [some limitations](../../reference/compatibility/mysql-compatibility/). Vitess also supports [Percona Server for MySQL](https://www.percona.com/software/mysql-database/percona-server) versions 5.7 to 8.0. + +{{< info >}}For new Vitess installations, MySQL or Percona Server for MySQL version 8 are recommended.{{< /info >}} + +## See also + ++ [MySQL Compatibility](../../reference/compatibility/mysql-compatibility/) diff --git a/content/en/docs/19.0/overview/whatisvitess.md b/content/en/docs/19.0/overview/whatisvitess.md new file mode 100644 index 000000000..4dc39d80f --- /dev/null +++ b/content/en/docs/19.0/overview/whatisvitess.md @@ -0,0 +1,69 @@ +--- +title: What Is Vitess +weight: 1 +featured: true +--- + +Vitess is a database solution for deploying, scaling and managing large clusters of open-source database instances. It currently supports MySQL and Percona Server for MySQL. It's architected to run as effectively in a public or private cloud architecture as it does on dedicated hardware. It combines and extends many important SQL features with the scalability of a NoSQL database. Vitess can help you with the following problems: + +1. Scaling a SQL database by allowing you to shard it, while keeping application changes to a minimum. +2. Migrating from bare-metal or VMs to a private or public cloud. +3. Deploying and managing a large number of SQL database instances. + +Vitess includes compliant JDBC and Go database drivers using a native query protocol. Additionally, it implements the MySQL server protocol which is compatible with virtually any other language. + +Vitess served all YouTube database traffic for over five years. Many enterprises have now adopted Vitess for their production needs. + +## Features + +* Performance + - Connection pooling - Multiplex front-end application queries onto a pool of MySQL connections to optimize performance. + - Query de-duping – Reuse results of an in-flight query for any identical requests received while the in-flight query was still executing. + - Transaction manager – Limit number of concurrent transactions and manage timeouts to optimize overall throughput. + +* Protection + - Query rewriting and sanitization – Add limits and avoid non-deterministic updates. + - Query blocking – Customize rules to prevent potentially problematic queries from hitting your database. + - Query killing – Terminate queries that take too long to return data. + - Table ACLs – Specify access control lists (ACLs) for tables based on the connected user. + +* Monitoring + - Performance analysis tools let you monitor, diagnose, and analyze your database performance. + +* Topology Management Tools + - Cluster management tools (handles planned and unplanned failovers) + - Web-based management GUI + - Designed to work in multiple data centers / regions + +* Sharding + - Virtually seamless dynamic re-sharding + - Vertical and Horizontal sharding support + - Multiple sharding schemes, with the ability to plug-in custom ones + +## Comparisons to other storage options + +The following sections compare Vitess to two common alternatives, a vanilla MySQL implementation and a NoSQL implementation. + +### Vitess vs. Vanilla MySQL + +Vitess improves a vanilla MySQL implementation in several ways: + +| Vanilla MySQL | Vitess | +|:--|:--| +| Every MySQL connection has a memory overhead that ranges between 256KB and almost 3MB, depending on which MySQL release you're using. As your user base grows, you need to add RAM to support additional connections, but the RAM does not contribute to faster queries. In addition, there is a significant CPU cost associated with obtaining the connections. | Vitess creates very lightweight connections. Vitess' connection pooling feature uses Go's concurrency support to map these lightweight connections to a small pool of MySQL connections. As such, Vitess can easily handle thousands of connections. | +| Poorly written queries, such as those that don't set a LIMIT, can negatively impact database performance for all users. | Vitess employs a SQL parser that uses a configurable set of rules to rewrite queries that might hurt database performance. | +| Sharding is a process of partitioning your data to improve scalability and performance. MySQL lacks native sharding support, requiring you to write sharding code and embed sharding logic in your application. | Vitess supports a variety of sharding schemes. It can also migrate tables into different databases and scale the number of shards up or down. These functions are performed non-intrusively, completing most data transitions with just a few seconds of read-only downtime. | +| A MySQL cluster using replication for availability has a primary database and a few replicas. If the primary fails, a replica should become the new primary. This requires you to manage the database lifecycle and communicate the current system state to your application. | Vitess helps to manage the lifecycle of your database servers. It supports and automatically handles various scenarios, including primary failure detection and recovery. It also has support for data backups and restores. | +| A MySQL cluster can have custom database configurations for different workloads, like a primary database for writes, fast read-only replicas for web clients, slower read-only replicas for batch jobs, and so forth. If the database has horizontal sharding, the setup is repeated for each shard, and the app needs baked-in logic to know how to find the right database. | Vitess uses a topology backed by a consistent data store, like etcd or ZooKeeper. This means the cluster view is always up-to-date and consistent for different clients. Vitess also provides a proxy that routes queries efficiently to the most appropriate MySQL instance. | + + +### Vitess vs. NoSQL + +If you're considering a NoSQL solution primarily because of concerns about the scalability of MySQL, Vitess might be a more appropriate choice for your application. While NoSQL provides great support for unstructured data, Vitess still offers several benefits not available in NoSQL datastores: + +| NoSQL | Vitess | +|:--|:--| +| NoSQL databases do not define relationships between database tables, and only support a subset of the SQL language. | Vitess is not a simple key-value store. It supports complex query semantics such as where clauses, JOINS, aggregation functions, and more. | +| NoSQL datastores do not usually support transactions. | Vitess supports transactions. | +| NoSQL solutions have custom APIs, leading to custom architectures, applications, and tools. | Vitess adds very little variance to MySQL, a database that most people are already accustomed to working with. | +| NoSQL solutions provide limited support for database indexes compared to MySQL. | Vitess allows you to use all of MySQL's indexing functionality to optimize query performance. | diff --git a/content/en/docs/19.0/reference/_index.md b/content/en/docs/19.0/reference/_index.md new file mode 100644 index 000000000..3d086453c --- /dev/null +++ b/content/en/docs/19.0/reference/_index.md @@ -0,0 +1,7 @@ +--- +title: Reference +description: Detailed information about specific Vitess functionality +weight: 5 +aliases: ['/docs/advanced/'] +--- + diff --git a/content/en/docs/19.0/reference/backup-and-restore/_index.md b/content/en/docs/19.0/reference/backup-and-restore/_index.md new file mode 100644 index 000000000..c072654b6 --- /dev/null +++ b/content/en/docs/19.0/reference/backup-and-restore/_index.md @@ -0,0 +1,7 @@ +--- +title: Backup and Restore +description: "Backup and Restore Reference" +weight: 10 +aliases: ['/docs/reference/backup-and-restore/'] +skip_sections: true +--- diff --git a/content/en/docs/19.0/reference/backup-and-restore/metrics.md b/content/en/docs/19.0/reference/backup-and-restore/metrics.md new file mode 100644 index 000000000..57d89f091 --- /dev/null +++ b/content/en/docs/19.0/reference/backup-and-restore/metrics.md @@ -0,0 +1,128 @@ +--- +title: Metrics +description: Metrics related to backup and restore functionality +weight: 10 +--- + +Backup and restore operations export several metrics using the expvars interface. These are available at the `/debug/vars` endpoint of Vtbackup's and VTTablet's http status pages. [More details can be found here](../../features/monitoring/#3-push-based-metrics-system). + +## Backup metrics + +Metrics related to backup operations are available in both Vtbackup and VTTablet. + +#### BackupBytes, BackupCount, BackupDurationNanoseconds + +Depending on the Backup Engine and Backup Storage in-use, a backup may be a complex pipeline of operations, including but not limited to: + + * Reading files from disk. + * Compressing files. + * Uploading compress files to cloud object storage. + +These operations are counted and timed, and the number of bytes consumed or produced by each stage of the pipeline are counted as well. + +## Restore metrics + +Metrics related to restore operations are available in both Vtbackup and VTTablet. + +#### RestoreBytes, RestoreCount, RestoreDurationNanoseconds + +Depending on the Backup Engine and Backup Storage in-use, a restore may be a complex pipeline of operations, including but not limited to: + + * Downloading compressed files from cloud object storage. + * Decompressing files. + * Writing decompressed files to disk. + +These operations are counted and timed, and the number of bytes consumed or produced by each stage of the pipeline are counted as well. + +#### RestoredBackupTime, RestorePosition + +_RestoredBackupTime_ captures the timestamp associated with the backup from which the current process was restored. _RestorePosition_ captures the GTID position associated with that backup. + +## Vtbackup metrics + +Vtbackup exports some metrics which are not available elsewhere. + +#### DurationByPhaseSeconds + +Vtbackup fetches the last backup, restores it to an empty mysql installation, replicates recent changes into that installation, and then takes a backup of that installation. + +_DurationByPhaseSeconds_ exports timings for these individual phases. + +
+ +## Example +**A snippet of vtbackup metrics after running it against the local example after creating the initial cluster** + +(Processed with `jq` for readability.) + +``` +{ + "BackupBytes": { + "BackupEngine.Builtin.Source:Read": 4777, + "BackupEngine.Builtin.Compressor:Write": 4616, + "BackupEngine.Builtin.Destination:Write": 162, + "BackupStorage.File.File:Write": 163 + }, + "BackupCount": { + "-.-.Backup": 1, + "BackupEngine.Builtin.Source:Open": 161, + "BackupEngine.Builtin.Source:Close": 322, + "BackupEngine.Builtin.Compressor:Close": 161, + "BackupEngine.Builtin.Destination:Open": 161, + "BackupEngine.Builtin.Destination:Close": 322 + }, + "BackupDurationNanoseconds": { + "-.-.Backup": 4188508542, + "BackupEngine.Builtin.Source:Open": 10649832, + "BackupEngine.Builtin.Source:Read": 55901067, + "BackupEngine.Builtin.Source:Close": 960826, + "BackupEngine.Builtin.Compressor:Write": 278358826, + "BackupEngine.Builtin.Compressor:Close": 79358372, + "BackupEngine.Builtin.Destination:Open": 16456627, + "BackupEngine.Builtin.Destination:Write": 11021043, + "BackupEngine.Builtin.Destination:Close": 17144630, + "BackupStorage.File.File:Write": 10743169 + }, + "DurationByPhaseSeconds": { + "InitMySQLd": 2, + "RestoreLastBackup": 6, + "CatchUpReplication": 1, + "TakeNewBackup": 4 + }, + "RestoreBytes": { + "BackupEngine.Builtin.Source:Read": 1095, + "BackupEngine.Builtin.Decompressor:Read": 950, + "BackupEngine.Builtin.Destination:Write": 209, + "BackupStorage.File.File:Read": 1113 + }, + "RestoreCount": { + "-.-.Restore": 1, + "BackupEngine.Builtin.Source:Open": 161, + "BackupEngine.Builtin.Source:Close": 322, + "BackupEngine.Builtin.Decompressor:Close": 161, + "BackupEngine.Builtin.Destination:Open": 161, + "BackupEngine.Builtin.Destination:Close": 322 + }, + "RestoreDurationNanoseconds": { + "-.-.Restore": 6204765541, + "BackupEngine.Builtin.Source:Open": 10542539, + "BackupEngine.Builtin.Source:Read": 104658370, + "BackupEngine.Builtin.Source:Close": 773038, + "BackupEngine.Builtin.Decompressor:Read": 165692120, + "BackupEngine.Builtin.Decompressor:Close": 51040, + "BackupEngine.Builtin.Destination:Open": 22715122, + "BackupEngine.Builtin.Destination:Write": 41679581, + "BackupEngine.Builtin.Destination:Close": 26954624, + "BackupStorage.File.File:Read": 102416075 + }, + "RestorePosition": "MySQL56/f00e54ca-0fbf-11ee-ad84-eddb850690bf:1-61", + "RestoredBackupTime": "2023-06-21T00:39:00Z", +} +``` + +Some notes to help understand these metrics: + + * `BackupBytes["BackupStorage.File.File:Write"]` measures how many bytes were read from disk by the `file` Backup Storage implementation during the backup phase. + * `DurationByPhaseSeconds["CatchUpReplication"]` measures how long it took to catch-up replication after the restore phase. + * `DurationByPhaseSeconds["RestoreLastBackup"]` measures to the duration of the restore phase. + * `RestoreDurationNanoseconds["-.-.Restore"]` also measures to the duration of the restore phase. diff --git a/content/en/docs/19.0/reference/compatibility/_index.md b/content/en/docs/19.0/reference/compatibility/_index.md new file mode 100644 index 000000000..9e6afdc21 --- /dev/null +++ b/content/en/docs/19.0/reference/compatibility/_index.md @@ -0,0 +1,6 @@ +--- +title: Compatibility +description: Reference documents for MySQL compatibility with Vitess +weight: 5 +--- + diff --git a/content/en/docs/19.0/reference/compatibility/mysql-compatibility.md b/content/en/docs/19.0/reference/compatibility/mysql-compatibility.md new file mode 100644 index 000000000..04d19f50c --- /dev/null +++ b/content/en/docs/19.0/reference/compatibility/mysql-compatibility.md @@ -0,0 +1,223 @@ +--- +title: MySQL Compatibility +weight: 1 +aliases: ['/docs/reference/mysql-server-protocol/', '/docs/reference/mysql-compatibility/'] +--- + +Vitess supports MySQL and gRPC server protocol. This allows Vitess to be a drop-in replacement for MySQL Server without any changes to application code. +As Vitess is a distributed system, it is important to understand the differences between Vitess and MySQL on compatibility. + +## Transaction Model + +Vitess provides MySQL default semantics i.e. `REPEATABLE READ` for single-shard transactions. For multi-shard transactions the semantics change to `READ COMMITTED`. +The clients can change the shard level transaction mode with `SET` statement on a connection. + +## SQL Support + +The following describes some differences in query handling between Vitess and MySQL. +The Vitess team maintains a list of [unsupported queries](https://github.com/vitessio/vitess/blob/main/go/vt/vtgate/planbuilder/testdata/unsupported_cases.json) which is kept up-to-date as we add support for new constructs. + +This is an area of active development in Vitess. Any unsupported query can be raised as an issue in the [Vitess GitHub Project](https://github.com/vitessio/vitess/issues/new/choose). + +### DDL + +Vitess supports all DDL queries. It offers both [managed, online schema changes](../../../user-guides/schema-changes/managed-online-schema-changes) and non-managed DDL. +It is recommended to use Vitess's managed schema changes, which offer non-blocking, trackable, failure agnostic, revertible, concurrent changes, and more. Read more about [making schema changes](../../../user-guides/schema-changes). + +### Join, Subqueries, Union, Aggregation, Grouping, Having, Ordering, Limit Queries + +Vitess supports most of these types of queries. It is recommended to leave [schema tracking](../../features/schema-tracking) enabled in order to fully utilize the available support. + +### Prepared Statements + +Vitess supports prepared statements via both the MySQL binary protocol and the [`PREPARE`, `EXECUTE` and `DEALLOCATE` SQL statements](https://dev.mysql.com/doc/refman/8.0/en/sql-prepared-statements.html). + +### Start Transaction +There are multiple ways to start a transaction like `begin`, `start transaction` and `start transaction [transaction_characteristic [, transaction_characteristic] ...]` with several modifiers that control transaction characteristics. +```sql +transaction_characteristic: { + WITH CONSISTENT SNAPSHOT + | READ WRITE + | READ ONLY +} +``` +The scope of these modifications is limited to the next transaction only. +These modifications have a special purpose and more can be read about in the [MySQL reference manual](https://dev.mysql.com/doc/refman/8.0/en/commit.html). + +### Set Transaction +Set Transaction statement is used to change the isolation level or access mode for transactions. +Vitess as of now **only** supports modification of isolation level at the session scope. +The change in isolation level only changes the shard level transaction isolation level and not the global Vitess level. + +More details about the isolation level can be read in the [MySQL reference manual](https://dev.mysql.com/doc/refman/8.0/en/set-transaction.html). + +### Stored Procedures + +Calling stored procedures using CALL is only supported for: + +* unsharded keyspaces +* if you directly target a specific shard + +There are further limitations to calling stored procedures using CALL: + +* The stored procedure CALL cannot return any results +* Only IN parameters are supported +* If you use transactions, the transaction state cannot be changed by the stored procedure. + + For example, if there is a transaction open at the beginning of the CALL, a transaction must still be open after the procedure finishes. Likewise, if no transaction is open at the beginning of the CALL, the stored procedure must not leave an open transaction after execution finishes. + +CREATE PROCEDURE is not supported. You have to create the procedure directly on the underlying MySQL servers and not through Vitess. + +### Views +Views are supported for sharded keyspaces as an experimental feature, it has to be enabled using: `--enable-views` on VTGate and `--queryserver-enable-views` on VTTablet. Views are only readable. + +Here is an example of how to create a view: + +```sql +CREATE VIEW my_view AS SELECT id, col FROM user +``` + +When using the view in a `SELECT` statement it will be rewritten to a derived table: + +```sql +-- the query: +SELECT id FROM my_view +-- will be rewritten to: +SELECT id FROM (SELECT id, col FROM user) as my_view; +``` + +> **Limitations**: +> +> - The table referenced by the view must belong to the same keyspace as the view's. +> +> - Views are only readable. Updatable views are not supported. + +The [RFC for views support](https://github.com/vitessio/vitess/issues/11559) is available on GitHub. + +### Temporary Tables + +Vitess has limited support for temporary tables. It works only for unsharded keyspaces. + +If the user creates a temporary table then the session will start using reserved connections for any query sent on that session. + +The query plans generated by this session will not be cached. It will still continue to use the query plan cached from other non-temporary table sessions. + +### USE Statements + +Vitess allows you to select a keyspace using the MySQL `USE` statement, and corresponding binary API used by client libraries. SQL statements can refer to a table in another keyspace by using the standard _dot_ notation: + +```sql +SELECT * FROM my_other_keyspace.table; +``` + +Vitess extends this functionality further by allowing you to select a specific shard and tablet-type within a `USE` statement (backticks are important): + +```sql +-- `KeyspaceName:shardKeyRange@tabletType` +USE `mykeyspace:-80@rdonly` +``` + +A similar effect can be achieved by using a database name like `mykeyspace:-80@rdonly` in your MySQL application client connection string. + +### Window Functions and CTEs + +Vitess does not yet support Window Functions or Common Table Expressions. + +### Killing running queries + +In v18, Vitess introduced the ability to terminate running queries using the [`KILL` command](https://dev.mysql.com/doc/refman/8.0/en/kill.html) through VTGate. +To execute a "kill connection" or "kill query" statement, the client needs to establish a new connection. +This behavior is similar to when a user on the MySQL shell client terminates a command by pressing ctrl+c. + +The [RFC](https://github.com/vitessio/vitess/issues/13438) highlights the current limitation of the `Kill statement` support. + +Alternatively, +- [query_timeout_ms](../../../user-guides/configuration-advanced/comment-directives/#query-timeouts-query_timeout_ms) query comment directive can be set to define a query timeout. This ensures that the query either returns a result or aborts within the specified time. +- [mysql_server_query_timeout](../../programs/vtgate/) command-line flag can be set on VTGate to establish a default timeout. + +Vitess does have strict query timeouts for OLTP workloads (see below). + +### Workload + +By default, Vitess applies specific limitations on the execution time and the number of rows a query can return. +These limitations can be modified by adjusting the parameters like `queryserver-config-query-timeout`, `queryserver-config-transaction-timeout` and more in [vttablet](../../programs/vttablet/). +This default workload mode is referred as `OLTP`. This can be disabled by switching to `OLAP` mode by executing the following SQL statement: + +```sql +set workload = olap; +``` + +### SELECT ... INTO Statement + +The `SELECT ... INTO` form of `SELECT` in MySQL enables a query result to be stored in variables or written to a file. Vitess supports `SELECT ... INTO DUMFILE` and `SELECT ... INTO OUTFILE` constructs for unsharded keyspaces but does not support storing results in variable. Moreover, the position of `INTO` must be towards the end of the query and not in the middle. An example of a correct query is as follows: +```sql +SELECT * FROM INTO OUTFILE 'x.txt' FIELDS TERMINATED BY ';' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\t' LINES TERMINATED BY '\n' +``` +For sharded keyspaces this statement can still be used but only after specifying the exact shard with a [USE Statement](#use-statements). + +### LOAD DATA Statement + +`LOAD DATA` is the complement of `SELECT ... INTO OUTFILE` that reads rows from a text file into a table at a very high speed. Just like `SELECT ... INTO` statement, `LOAD DATA` is also supported in unsharded keyspaces. An example of a correct query is as follows: +```sql +LOAD DATA INFILE 'x.txt' INTO REPLACE TABLE FIELDS TERMINATED BY ';' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\t' LINES TERMINATED BY '\n' +``` +For sharded keyspaces this statement can still be used but only after specifying the exact shard with a [USE Statement](#use-statements). + +### Create/Drop Database + +Vitess does not support CREATE and DROP DATABASE queries out of the box. + +However, a plugin mechanism is available that can be used to provision databases. +The plugin has to take care of creating and dropping the database, and update the topology & VSchema so that Vitess can start receiving queries for the new keyspace. + +The plugin should implement the `DBDDLPlugin` interface, and be saved into a new file in the `go/vt/vtgate/engine/` directory. + +```go +type DBDDLPlugin interface { + CreateDatabase(ctx context.Context, name string) error + DropDatabase(ctx context.Context, name string) error +} +``` + +It must then register itself by calling `DBDDLRegister`. +You can take a look at the `dbddl_plugin.go` in the engine package for an example of how it's done. +Finally, you need to add a command line flag to vtgate to have it use the new plugin: `--dbddl_plugin=myPluginName` + +## Cross-shard Transactions + +Vitess supports multiple [transaction modes](../../../user-guides/configuration-advanced/shard-isolation-atomicity): `SINGLE`, `MULTI` and `TWOPC` . + +The default mode is MULTI i.e. multi-shard transactions as best-effort. A transaction that affects only one shard will be fully ACID complaint. +When a transactions affects multiple shards, any failure on one or more shards will rollback the effect of that query. +Committing the multi-shard transaction issues commits to the participating shards in a particular order. This allows the application or user to undo the effects of partial commits in case of failures. + +## Auto Increment + +Tables in sharded keyspaces should not be defined using the `auto_increment` column attribute, as the values generated will not be unique across shards. +It is recommended to use [Vitess Sequences](../../features/vitess-sequences) instead. The semantics are very similar to `auto_increment` and the differences are documented. + +## Character Set and Collation + +Vitess supports ~99% of MySQL collations. More details can be found [here](../../../user-guides/configuration-basic/collations). + +## Data Types + +Vitess supports all of the data types available in MySQL. Using the `FLOAT` data type as part of a `PRIMARY KEY` is strongly discouraged, since features such as filtered replication and VReplication will not correctly be able to detect which rows should be included as part of a modification. + +## SQL Mode + +Vitess behaves similar to the `STRICT_TRANS_TABLES` sql mode, and does not recommend changing the SQL Mode setting. + +## Network Protocol + +### Authentication Plugins + +Vitess supports both 5.7 and 8.0 authentication. E.g. `mysql_native_password`, `caching_sha2_password`, etc. + +### Transport Security + +To configure VTGate to support `TLS` set `--mysql_server_ssl_cert` and `--mysql_server_ssl_key`. Client certificates can also be mandated by setting `--mysql_server_ssl_ca`. If there is no CA specified then TLS is optional. + +### X Dev API + +Vitess does not support [X Dev API](https://dev.mysql.com/doc/x-devapi-userguide/en/). diff --git a/content/en/docs/19.0/reference/errors/_index.md b/content/en/docs/19.0/reference/errors/_index.md new file mode 100644 index 000000000..7aa609b75 --- /dev/null +++ b/content/en/docs/19.0/reference/errors/_index.md @@ -0,0 +1,6 @@ +--- +title: Errors +description: Detailed information about errors that the user might run into +weight: 6 +--- + diff --git a/content/en/docs/19.0/reference/errors/query-serving.md b/content/en/docs/19.0/reference/errors/query-serving.md new file mode 100644 index 000000000..fa1455d21 --- /dev/null +++ b/content/en/docs/19.0/reference/errors/query-serving.md @@ -0,0 +1,108 @@ +--- +title: Query Serving +weight: 1 +description: Errors a users might encounter while querying Vitess +--- + +{{< info >}} +These error messages are internal to Vitess. If you are getting other errors from MySQL you can check them on this MySQL error [page](https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html). +{{< /info >}} + +## New Errors + + +| ID | Description | Error | MySQL Error Code | SQL State | +| --- | --- | --- | --- | --- | +| VT03001 | This aggregation function only takes a single argument. | aggregate functions take a single argument '%s' | 1149 | 42000 | +| VT03002 | This schema change is not allowed. You cannot change the keyspace of a table. | changing schema from '%s' to '%s' is not allowed | 1450 | HY000 | +| VT03003 | The specified table in this DELETE statement is unknown. | unknown table '%s' in MULTI DELETE | 1109 | 42S02 | +| VT03004 | You cannot delete something that is not a real MySQL table. | the target table %s of the DELETE is not updatable | 1288 | HY000 | +| VT03005 | The planner does not allow grouping on certain field. For instance, aggregation function. | cannot group on '%s' | 1056 | 42000 | +| VT03006 | The number of columns you want to insert do not match the number of columns of your SELECT query. | column count does not match value count at row 1 | 1136 | 21S01 | +| VT03007 | You need to add a keyspace qualifier. | keyspace not specified | 0 | | +| VT03008 | The given token is not usable in this situation. Please refer to the MySQL documentation to learn more about your token's syntax. | incorrect usage/placement of '%s' | 1234 | 42000 | +| VT03009 | You cannot assign this type to the given variable. | unexpected value type for '%s': %v | 1231 | 42000 | +| VT03010 | You cannot set the given variable as it is a read-only variable. | variable '%s' is a read only variable | 1238 | HY000 | +| VT03011 | The given value type is not accepted. | invalid value type: %v | 0 | | +| VT03012 | The syntax is invalid. Please refer to the MySQL documentation for the proper syntax. | invalid syntax: %s | 0 | | +| VT03013 | This table or alias name is already use. Please use another one that is unique. | not unique table/alias: '%s' | 1066 | 42000 | +| VT03014 | The given column is unknown. | unknown column '%d' in '%s' | 1054 | 42S22 | +| VT03015 | Cannot assign multiple values to a column in an update statement. | column has duplicate set values: '%v' | 0 | | +| VT03016 | The given column is unknown in the vindex table. | unknown vindex column: '%s' | 0 | | +| VT03017 | This vstream where clause can only be a greater than filter. | where clause can only be of the type 'pos > ' | 1149 | 42000 | +| VT03018 | You cannot use the NEXT syntax on a table that is not a sequence table. | NEXT used on a non-sequence table | 0 | | +| VT03019 | The given column was not found or is not available. | column %s not found | 0 | | +| VT03020 | The given column was not found in the subquery. | column %s not found in subquery | 0 | | +| VT03021 | The given column is ambiguous. You can use a table qualifier to make it unambiguous. | ambiguous column reference: %v | 0 | | +| VT03022 | The given column cannot be found. | column %v not found in %v | 0 | | +| VT03023 | When targeting a range of shards, Vitess does not know which shard to send the INSERT to. | INSERT not supported when targeting a key range: %s | 0 | | +| VT03024 | The query cannot be prepared using the user defined variable as it does not exists for this session. | '%s' user defined variable does not exists | 0 | | +| VT03025 | The execute statement have wrong number of arguments | Incorrect arguments to %s | 1210 | HY000 | +| VT05001 | The given database does not exist; Vitess cannot drop it. | cannot drop database '%s'; database does not exists | 1008 | HY000 | +| VT05002 | The given database does not exist; Vitess cannot alter it. | cannot alter database '%s'; unknown database | 1049 | 42000 | +| VT05003 | The given database does not exist in the VSchema. | unknown database '%s' in vschema | 1049 | 42000 | +| VT05004 | The given table is unknown. | table '%s' does not exist | 1109 | 42S02 | +| VT05005 | The given table does not exist in this keyspace. | table '%s' does not exist in keyspace '%s' | 1146 | 42S02 | +| VT05006 | The given system variable is unknown. | unknown system variable '%s' | 1193 | HY000 | +| VT05007 | Table information is not available. | no table info | 0 | | +| VT06001 | The given database name already exists. | cannot create database '%s'; database exists | 1007 | HY000 | +| VT07001 | Kill statement is not allowed. More in docs about how to enable it and its limitations. | %s | 1095 | HY000 | +| VT09001 | the table does not have a primary vindex, the operation is impossible. | table '%s' does not have a primary vindex | 1173 | 42000 | +| VT09002 | This type of DML statement is not allowed on a replica target. | %s statement with a replica target | 1874 | HY000 | +| VT09003 | A vindex column is mandatory for the insert, please provide one. | INSERT query does not have primary vindex column '%v' in the column list | 0 | | +| VT09004 | You need to provide the list of columns you want to insert, or provide a VSchema with authoritative columns. If schema tracking is disabled you can enable it to automatically have authoritative columns. | INSERT should contain column list or the table should have authoritative columns in vschema | 0 | | +| VT09005 | A database must be selected. | no database selected: use keyspace<:shard><@type> or keyspace<[range]><@type> (<> are optional) | 1046 | 3D000 | +| VT09006 | VITESS_MIGRATION commands work only on primary tablets, you must send such commands to a primary tablet. | %s VITESS_MIGRATION works only on primary tablet | 0 | | +| VT09007 | VITESS_THROTTLED_APPS commands work only on primary tablet, you must send such commands to a primary tablet. | %s VITESS_THROTTLED_APPS works only on primary tablet | 0 | | +| VT09008 | vexplain queries/all will actually run queries. `/*vt+ EXECUTE_DML_QUERIES */` must be set to run DML queries in vtexplain. Example: `vexplain /*vt+ EXECUTE_DML_QUERIES */ queries delete from t1` | vexplain queries/all will actually run queries | 0 | | +| VT09009 | Stream is only supported for primary tablets, please use a stream on those tablets. | stream is supported only for primary tablet type, current type: %v | 0 | | +| VT09010 | SHOW VITESS_THROTTLER STATUS works only on primary tablet. | SHOW VITESS_THROTTLER STATUS works only on primary tablet | 0 | | +| VT09011 | The prepared statement is not available | Unknown prepared statement handler (%s) given to %s | 1243 | HY000 | +| VT09012 | This type of statement is not allowed on the given tablet. | %s statement with %s tablet not allowed | 0 | | +| VT09013 | Durability policy wants Vitess to use semi-sync, but the MySQL instances don't have the semi-sync plugin loaded. | semi-sync plugins are not loaded | 0 | | +| VT09014 | The vindex cannot be used as table in DML statement | vindex cannot be modified | 0 | | +| VT09015 | This query cannot be planned without more information on the SQL schema. Please turn on schema tracking or add authoritative columns information to your VSchema. | schema tracking required | 0 | | +| VT09016 | SET DEFAULT is not supported by InnoDB | Cannot delete or update a parent row: a foreign key constraint fails | 1451 | 23000 | +| VT10001 | Foreign key constraints are not allowed, see https://vitess.io/blog/2021-06-15-online-ddl-why-no-fk/. | foreign key constraints are not allowed | 0 | | +| VT12001 | This statement is unsupported by Vitess. Please rewrite your query to use supported syntax. | unsupported: %s | 0 | | +| VT12002 | Vitess does not support cross shard foreign keys. | unsupported: cross-shard foreign keys | 0 | | +| VT13001 | This error should not happen and is a bug. Please file an issue on GitHub: https://github.com/vitessio/vitess/issues/new/choose. | [BUG] %s | 0 | | +| VT13002 | This error should not happen and is a bug. Please file an issue on GitHub: https://github.com/vitessio/vitess/issues/new/choose. | unexpected AST struct for query: %s | 0 | | +| VT14001 | The connection failed. | connection error | 0 | | +| VT14002 | No available connection. | no available connection | 0 | | +| VT14003 | No connection for the given tablet. | no connection for tablet %v | 0 | | +| VT14004 | The specified keyspace could not be found. | cannot find keyspace for: %s | 0 | | +| VT14005 | Failed to read sidecar database identifier. | cannot lookup sidecar database for keyspace: %s | 0 | | + + +## Old Errors +| Error Number | Error State | Message | Meaning | +| :--: |:--: | :-- | -- | +| 1192 | HY000 | Can't execute the given command because you have an active transaction | The provided statement cannot be executed inside a transaction. | +| 1231 | 42000 | invalid transaction_mode: %s | Valid transaction_mode values are 'SINGLE', 'MULTI' or 'TWOPC'. | +| 1231 | 42000 | invalid workload: %s | Valid workload values are 'OLTP', 'OLAP' or 'DBA'. | +| 1231 | 42000 | invalid DDL strategy: %s | Valid DDL strategies are gh-ost, pt-osc. | +| 1690 | 22003 | %s value is out of range in %v [+,-,*,/] %v | Arithmetic operation lead to out of range value for the type. | +| 1047 | 42000 | connection ID and transaction ID do not exist | The session is pointing to a transaction and/or reserved connection that is not valid. | +| 1105 | HY000 | %d is not a boolean | Tried setting a system variable to a value that could not be converted a boolean value. | +| 1105 | HY000 | %s is not a sequence | The given table is not a sequence table. | +| 1105 | HY000 | %v cannot be converted to a go type | This type can't be represented as a golang value. | +| 1105 | HY000 | 2pc is not enabled | This functionality requires 2PC. Read more about 'transaction_mode' to learn how to enable it. | +| 1105 | HY000 | GTIDSet Mismatch: requested source position:%v, current target vrep position: %v | The requested GTIDSet does not exist in the vrep stream. | +| 1105 | HY000 | No target | TODO https://github.com/vitessio/vitess/blob/9542883311c0849c645cfb1b5c77ac761990b31b/go/vt/vttablet/tabletserver/state_manager.go#L376 | +| 1105 | HY000 | Unexpected error, DestinationKeyspaceID mapping to multiple shards | This is an internal error. If you see this error, please report it as a bug. | +| 1105 | HY000 | auto sequence generation can happen through single shard only, it is getting routed to %d shards | A sequence query has to be routed to a single shard, but this query was not. | +| 1105 | HY000 | could not parse value: '%s' | Tried parsing a value as a number but failed. | +| 1105 | HY000 | disallowed due to rule: %s | The query was not permitted to execute because the session was lacking permissions to do so. | +| 1105 | HY000 | invalid increment for sequence %s: %d | The given sequence increment is incorrect it should be equal or greater than zero. | +| 1105 | HY000 | invalid keyspace %v does not match expected %v | The given keyspace target does not match this tablet's keyspace name. | +| 1105 | HY000 | invalid shard %v does not match expected %v | The given shard target does not match this tablet's shard. | +| 1105 | HY000 | invalid table name: %s | The table name contains invalid characters. | +| 1105 | HY000 | [%d,'%s'] is not a boolean | This error will be returned if you try to set a variable to a value that can't be converted to a boolean value. | +| 1105 | HY000 | negative number cannot be converted to unsigned: %d | The column or variable is expecting an unsigned int, and negative numbers invalid here. | +| 1105 | HY000 | query arguments missing for %s | Argument expected but was missing. | +| 1105 | HY000 | require autocommit to be 1: got %s | Connection needs autocommit to be enabled, but it was not. | +| 1105 | HY000 | require sql_auto_is_null to be 0: got %s | Vitess requires the connection not use the auto_col functionality. | +| 1105 | HY000 | require sql_mode to be STRICT_TRANS_TABLES or STRICT_ALL_TABLES: got '%s' | Vitess requires the connection to be in STRICT mode; either or both of these settings need to be enabled. | +| 1105 | HY000 | unexpected rows from reading sequence %s (possible mis-route): %d | The sequence table used returned invalid results. | +| 1105 | HY000 | unsigned number overflows int64 value: %d | Tried to convert an unsigned integer into a signed integer, and the value overflows. | diff --git a/content/en/docs/19.0/reference/features/_index.md b/content/en/docs/19.0/reference/features/_index.md new file mode 100644 index 000000000..6d3b5e10c --- /dev/null +++ b/content/en/docs/19.0/reference/features/_index.md @@ -0,0 +1,6 @@ +--- +title: Features +description: Reference documents for Vitess features +weight: 1 +--- + diff --git a/content/en/docs/19.0/reference/features/connection-pools.md b/content/en/docs/19.0/reference/features/connection-pools.md new file mode 100644 index 000000000..d30eb0eb7 --- /dev/null +++ b/content/en/docs/19.0/reference/features/connection-pools.md @@ -0,0 +1,155 @@ +--- +title: VTTablet Connection Pools and Sizing +weight: 20 +--- + +VTTablet uses a variety of connection pools to connect to MySQLd. +Most of these can be controlled by vttablet options. +Note that almost all of these pools are **not** fixed size connection pools, and will grow on demand to the maximum configured sizes. +In older Vitess versions, v6.0 or before, some pools would eventually shrink again, but in recent Vitess versions a new pool connection is created when an old one reaches its idle timeout. +As a result, pools will now effectively never shrink. + +One thing to note is that each of these pools do not use unique MySQL usernames, so it can be hard from a MySQL process list to distinguish between different pool connections. +Consult the `_active` pool metrics (e.g. `vttablet_dba_conn_pool_active`) as the authoritative resource on how many MySQL protocol connections are in use for each pool. +In a similar fashion the `_exhausted` pool metrics (e.g. `vttablet_dba_conn_pool_exhausted`) can be used to see if a given pool has run out of connections (and how many times), since VTTablet startup. + +Note that a connection pool running out of connections is not necessarily a bad thing, since it limits the concurrency in the database. +As a result, connection pools should be sized mindful of the capacity of the underlying MySQL instance(s). + +## Pools: + +### transaction_pool and found_rows_pool + + * Max size (for each) controlled by: `--queryserver-config-transaction-cap` (default 20) + * metric: `vttablet_transaction_pool_capacity` + * metric: `vttablet_found_rows_pool_capacity` + * Used by transaction engine to manage transactions that require a dedicated connection. + The main pool for this use the **transaction_pool**. + The **found_rows_pool** is dedicated for connections where the client is using the `CLIENT_FOUND_ROWS` option. + For example, the `affected_rows` field return by the [MySQL protocol](https://dev.mysql.com/doc/internals/en/packet-OK_Packet.html) becomes the number of rows matched by the `WHERE` clause instead. + +### conn_pool + + * Max size controlled controlled by: `--queryserver-config-pool-size` (default 16) + * metric: `vttablet_conn_pool_capacity` + * Potentially uses `--db_app_user`, `--db_dba_user` and `--db_appdebug_user` i.e. defaults 'vt_app', 'vt_dba' and 'vt_appdebug' + * Used as the vttablet query engine "normal" (non-streaming) connections pool. + +### stream_conn_pool + + * Max size controlled by: `--queryserver-config-stream-pool-size` (default 200) + * metric: `vttablet_stream_conn_pool_capacity` + * Potentially uses `--db_app_user`, `--db_dba_user` and `--db_appdebug_user` + i.e. defaults 'vt_app', 'vt_dba' and 'vt_appdebug' + * Used as vttablet query engine streaming connections pool. All streaming queries that are not transactional should use this pool. + +### dba_conn_pool + + * 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` + Also used implicitly for various internal Vitess maintenance tasks (e.g. schema reloads, etc.) + +### app_conn_pool + + * 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` + +### tx_read_pool + + * Hardcoded (size 3) + * metric: `vttablet_tx_read_pool_capacity` + * vttablet user flag: `--db_dba_user` (default 'vt_dba') + * Used in the (non-default) TWOPC `transaction_mode` for metadata state management. + This pool will always be empty unless TWOPC is used. + +### Pools associated with online DDL + +#### online_ddl_executor_pool + + * Hardcoded (size 3) + * metric: `vttablet_online_ddl_executor_pool_capacity` + * Potentially uses `--db_app_user`, `--db_dba_user` and `--db_appdebug_user` i.e. defaults 'vt_app', 'vt_dba' and 'vt_appdebug' + * Used in Online DDL to during the actual process of running gh-ost or pt-osc. + +#### table_gc_pool + + * Hardcoded (default 2) + * metric: `vttablet_table_gc_pool_capacity` + * Potentially uses `--db_app_user`, `--db_dba_user` and `--db_appdebug_user` i.e. defaults 'vt_app', 'vt_dba' and 'vt_appdebug' + * Used in Online DDL to purge/evac/drop origin tables after Online DDL operations from them have been completed. + +## Other DB connections used without pools: + +### vttablet user flag: + +#### `--db_allprivs_user` + + * (default 'vt_allprivs') + * Created on demand by `vtctlclient ExecuteFetchAsAllPrivs` + +#### `--db_erepl_user` + + * (default 'vt_erepl') + * Used only if you setup replication explicitly from an external MySQL instance **without** front-ending that instance with a tablet. + This user is then used to login to the external MySQL. + +#### `--db_repl_user` + + * (default 'vt_repl') + * Used to setup MySQL replication between shard primary and replica instance types. + +#### `--db_filtered_user` + + * (default 'vt_filtered') + * Used by VReplication on the source (vstreamer) and target (vplayer) side when copying data. + +## Other relevant pool-related variables + +### vttablet user limit +Flag: `--transaction_limit_per_user` + + * (default 0.4) + * This flag determines the fraction of connections in the **transaction_pool** and **found_rows_pool** that can be used by a single user. + The username is passed to vttablet from vtgate. + If you are using a limited set of users, you may want to increase this limit. + Or disable this limit feature by setting `--transaction_limit_by_username` to `false` as the default is `true`. + This option only comes into play if the TX limiter is enabled by `--enable_transaction_limit`, which it is not by default. + +### vtgate system settings +Flag: `--enable_system_settings` + +This vtgate flag allows clients to modify a [subset of system settings](https://github.com/vitessio/vitess/blob/main/go/vt/sysvars/sysvars.go#L174-L217) on the MySQL. This is done using the mechanism of [reserved connection](../../query-serving/reserved-conn/#enabling-reserved-connections). +Once a reserved connection is created, it lives for the life of the vtgate client session. These connections live outside of the regular connection pool and as a result, the number of MySQL server connections used by +vttablet may become significantly higher than what you might expect based on the pool settings. + +### vttablet settings pool +Flag: `--queryserver-enable-settings-pool` + +This vttablet flag enables pooling of connections with modified settings. +This overcomes the issue described with the number of MySQL connections in [vtgate system settings](#vtgate-system-settings). +Both these flags should be enabled for clients to be able to modify system settings without foregoing the benefits of connection pooling. + + +## Calculating maximum db connections used by vttablet + +You can use the following formula to approximate the maximum MySQL connections per vttablet instance: +``` + --queryserver-config-transaction-cap x 2 (transaction_pool and found_rows_pool) + + --queryserver-config-pool-size (conn_pool) + + --queryserver-config-stream-pool-size (stream_conn_pool) + + --dba_pool_size (dba_conn_pool) + + --app_pool_size (app_conn_pool) + + 3 (tx_read_pool, hardcoded) + + 7 (online DDL) + + variable (on demand: for vreplication, MySQL replication, etc; should < 10) + + variable (reserved connections used by `enable_system_settings`) +``` + +{{< info >}} +Note that most servers will not use this many connections, since most workloads do not exercise all the pools. +{{< /info >}} + diff --git a/content/en/docs/19.0/reference/features/global-routing.md b/content/en/docs/19.0/reference/features/global-routing.md new file mode 100644 index 000000000..c3813db8e --- /dev/null +++ b/content/en/docs/19.0/reference/features/global-routing.md @@ -0,0 +1,153 @@ +--- +title: Global Routing +weight: 23 +--- + +# Global Table Routing +Vitess has an implicit feature of routing the queries to the appropriate keyspace based on the table specified in the `from` list. +This differs from the standard mysql, in mysql unqualified tables will fail if the correct database is not set on the connection. + +This feature works only for unique table names provided in the [VSchema](../../../vschema/), and only when no default keyspace is set on the connection. One exception to the uniqueness rule is [Reference Tables](../../../user-guides/vschema-guide/advanced-vschema/#reference-tables) that explicitly specify a `source` table. + +Example: +```sql +mysql> show keyspaces; ++----------+ +| Database | ++----------+ +| ks | +| customer | +| commerce | ++----------+ +3 rows in set (0.00 sec) +``` + +`ks` and `customer` are sharded keyspaces and `commerce` is an unsharded keyspace. + +Tables present in each of the keyspace. + +```sql +mysql> show tables from ks; ++--------------+ +| Tables_in_ks | ++--------------+ +| customer | +| matches | +| player | ++--------------+ +3 rows in set (0.00 sec) + +mysql> show tables from customer; ++--------------------+ +| Tables_in_customer | ++--------------------+ +| corder | +| customer | ++--------------------+ +2 rows in set (0.00 sec) + +mysql> show tables from commerce; ++--------------------+ +| Tables_in_commerce | ++--------------------+ +| customer_seq | +| order_seq | +| product | ++--------------------+ +3 rows in set (0.00 sec) +``` + +Without a default keyspace we can route to unique tables like `corder`, `product` and `player` but cannot route to `customer` + +```sql +mysql> show columns from corder; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| order_id | bigint | NO | PRI | NULL | | +| customer_id | bigint | YES | | NULL | | +| sku | varbinary(128) | YES | | NULL | | +| price | bigint | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +4 rows in set (0.01 sec) + +mysql> show columns from product; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| sku | varbinary(128) | NO | PRI | NULL | | +| description | varbinary(128) | YES | | NULL | | +| price | bigint | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +3 rows in set (0.00 sec) + +mysql> show columns from player; ++-----------+-------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-----------+-------------+------+-----+---------+-------+ +| player_id | bigint | NO | PRI | NULL | | +| name | varchar(50) | NO | | NULL | | ++-----------+-------------+------+-----+---------+-------+ +2 rows in set (0.00 sec) + +mysql> show columns from customer; +ERROR 1105 (HY000): ambiguous table reference: customer +``` + +With the default keyspace set to `customer` we can only query tables in `commerce` i.e `customer` and `corder`. +```sql +mysql> use customer +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Database changed +mysql> show columns from customer; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| customer_id | bigint | NO | PRI | NULL | | +| email | varbinary(128) | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +2 rows in set (0.01 sec) + +mysql> show columns from corder; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| order_id | bigint | NO | PRI | NULL | | +| customer_id | bigint | YES | | NULL | | +| sku | varbinary(128) | YES | | NULL | | +| price | bigint | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +4 rows in set (0.00 sec) + +mysql> show columns from product; +ERROR 1105 (HY000): table product not found +``` + +With a default keyspace set, the queries can be routed to other keyspaces by specifying the table qualifier. +```sql +mysql> use customer +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Database changed +mysql> show columns from ks.player; ++-----------+-------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-----------+-------------+------+-----+---------+-------+ +| player_id | bigint | NO | PRI | NULL | | +| name | varchar(50) | NO | | NULL | | ++-----------+-------------+------+-----+---------+-------+ +2 rows in set (0.00 sec) + +mysql> show columns from commerce.product; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| sku | varbinary(128) | NO | PRI | NULL | | +| description | varbinary(128) | YES | | NULL | | +| price | bigint | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +3 rows in set (0.00 sec) +``` diff --git a/content/en/docs/19.0/reference/features/img/vschema_arch.png b/content/en/docs/19.0/reference/features/img/vschema_arch.png new file mode 100644 index 000000000..ac1c9a969 Binary files /dev/null and b/content/en/docs/19.0/reference/features/img/vschema_arch.png differ diff --git a/content/en/docs/19.0/reference/features/messaging.md b/content/en/docs/19.0/reference/features/messaging.md new file mode 100644 index 000000000..8724ae323 --- /dev/null +++ b/content/en/docs/19.0/reference/features/messaging.md @@ -0,0 +1,224 @@ +--- +title: Vitess Messaging +--- + +Vitess messaging gives the application an easy way to schedule and manage work +that needs to be performed asynchronously. Under the covers, messages are +stored in a traditional MySQL table and therefore enjoy the following +properties: + +* **Scalable**: Because of Vitess's sharding abilities, messages can scale to + very large QPS or sizes. +* **Guaranteed delivery**: A message will be indefinitely retried until a + successful ack is received. +* **Non-blocking**: If the sending is backlogged, new messages continue to be + accepted for eventual delivery. +* **Adaptive**: Messages that fail delivery are backed off exponentially with + jitter to prevent thundering herds. +* **Analytics**: Acknowledged messages are retained for a period of time — dictated + by the `time_acked` value for the row and the `vt_purge_after` (seconds) value + provided for the table — and can be used for analytics. +* **Transactional**: Messages can be created or acked as part of an existing + transaction. The action will complete only if the commit succeeds. + +The properties of a message are chosen by the application. However, every +message needs a uniquely identifiable key. If the messages are stored in a +sharded table, the key must also be the primary vindex of the table. + +Although messages will generally be delivered in the order they're created, +this is not an explicit guarantee of the system. The focus is more on keeping +track of the work that needs to be done and ensuring that it was performed. +Messages are good for: + +* Handing off work to another system. +* Recording potentially time-consuming work that needs to be done + asynchronously. +* Accumulating work that could be done during off-peak hours. + +Messages are not a good fit for the following use cases: + +* Broadcasting each event to multiple subscribers. +* Ordered delivery is required. +* Real-time delivery properties are required. + +## Creating a message table + +The current implementation requires a base fixed schema with properties defined +using Vitess specific table `COMMENT` directives. The message table format is as +follows: + +```sql +create table my_message( + # required columns + id bigint NOT NULL COMMENT 'often an event id, can also be auto-increment or a sequence', + priority tinyint NOT NULL DEFAULT '50' COMMENT 'lower number priorities process first', + epoch bigint NOT NULL DEFAULT '0' COMMENT 'Vitess increments this each time it sends the message, and is used for incremental backoff doubling', + time_next bigint DEFAULT 0 COMMENT 'the earliest time the message will be sent in epoch nanoseconds. Must be null if time_acked is set', + time_acked bigint DEFAULT NULL COMMENT 'the time the message was acked in epoch nanoseconds. Must be null if time_next is set', + + # add as many custom fields here as required + # optional - these are suggestions + tenant_id bigint COMMENT 'offers a nice way to segment your messages', + message json, + + # required indexes + primary key(id), + index poller_idx(time_acked, priority, time_next desc) + + # add any secondary indexes or foreign keys - no restrictions +) comment 'vitess_message,vt_min_backoff=30,vt_max_backoff=3600,vt_ack_wait=30,vt_purge_after=86400,vt_batch_size=10,vt_cache_size=10000,vt_poller_interval=30' +``` + +The application-related columns are as follows: + +* `id`: can be any type. Must be unique (for sharded message tables, this will typically be your primary vindex column). +* `message`: can be any type. +* `priority`: messages with a lower priority will be processed first. + +The noted indexes are recommended for optimum performance. However, some +variation can be allowed to achieve different performance trade-offs. + +The comment section specifies additional configuration parameters. The fields +are as follows: + +* `vitess_message`: Indicates that this is a message table. +* `vt_min_backoff=30`: Set lower bound, in seconds, on exponential backoff for + message retries. If not set, defaults to `vt_ack_wait` _(optional)_ +* `vt_max_backoff=3600`: Set upper bound, in seconds, on exponential backoff for + message retries. The default value is infinite backoff _(optional)_ +* `vt_ack_wait=30`: Wait for 30 seconds for the *first* message send to be acked. + If one is not received within this time frame, the message will be resent. +* `vt_purge_after=86400`: Purge acked messages that are older than 86400 + seconds (1 day). +* `vt_batch_size=10`: Send up to 10 messages per gRPC packet. +* `vt_cache_size=10000`: Store up to 10,000 messages in the cache. If the demand + is higher, the rest of the items will have to wait for the next poller cycle. +* `vt_poller_interval=30`: Poll every 30 seconds for messages that should be + [re]sent. + +If any of the above fields not marked as optional are missing, Vitess will fail to load the table. No +operation will be allowed on a table that has failed to load. + +## Enqueuing messages + +The application can enqueue messages using a standard `INSERT` statement, for example: + +```sql +insert into my_message(id, message) values(1, '{"message": "hello world"}') +``` + +These inserts can be part of a regular transaction. Multiple messages can be +inserted into different tables. Avoid accumulating too many big messages within a +transaction as it consumes memory on the VTTablet side. At the time of commit, +memory permitting, all messages are instantly enqueued to be sent. + +Messages can also be created to be sent in the future: + + ```sql + insert into my_message(id, message, time_next) values(1, '{"message": "hello world"}', :future_time) + ``` + + `future_time` must be a unix timestamp expressed in nanoseconds. + +## Receiving messages + +Processes can subscribe to receive messages by sending a [`MessageStream`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate#Executor.MessageStream) +gRPC request to a `VTGate` or using the `stream * from ` SQL statement +(if using the interactive mysql command-line client you must also pass the +`-q`/`--quick` option): + +```mysql +$ mysql --quick +mysql> SET WORKLOAD=OLAP; +mysql> STREAM * FROM
; +``` + +
+ +If there are multiple subscribers, the messages will be delivered in a round-robin +fashion. Note that *this is not a broadcast*; each message will be sent to at most +one subscriber. + +The format for messages is the same as a standard Vitess `Result` received from +a `VTGate`. This means that standard database tools that understand query results +can also be message receivers. + +### Subsetting + +It's possible that you may want to subscribe to specific shards or groups of +shards while requesting messages. This is useful for partitioning or load +balancing. The `MessageStream` gRPC API call allows you to specify these +constraints. The request parameters are as follows: + +* `Name`: Name of the message table. +* `Keyspace`: Keyspace where the message table is present. +* `Shard`: For unsharded keyspaces, this is usually "0". However, an empty + shard will also work. For sharded keyspaces, a specific shard name can be + specified. +* `KeyRange`: If the keyspace is sharded, streaming will be performed only from + the shards that match the range. This must be an exact match. + +## Acknowledging messages + +A received and processed (you've completed some meaningful work based on the +message contents received) message can be acknowledged using the `MessageAck` +gRPC API call. This call accepts the following parameters: + +* `Name`: Name of the message table. +* `Keyspace`: Keyspace where the message table is present. This field can be + empty if the table name is unique across all keyspaces. +* `Ids`: The list of ids that need to be acked. + +Once a message is successfully acked, it will never be resent. + +## Exponential backoff + +For a message that was successfully sent we will wait for the specified `vt_ack_wait` +time. If no ack is received by then, it will be resent. The next attempt will be 2x +the previous wait and this delay is doubled for every subsequent attempt — bound by +`vt_min_backoff` and `vt_max_backoff` — with some added jitter (up to 33%) to avoid +thundering herds. + +## Purging + +Messages that have been successfully acked will be deleted after their age +exceeds the time period specified by `vt_purge_after`. + +## Advanced usage + +The `MessageAck` functionality is currently a gRPC API call and cannot be used +from the SQL interface. However, you can manually ack messages using a regular +DML query like this: + +```sql +update my_message set time_acked = :time_acked, time_next = null where id in ::ids and time_acked is null +``` + +You can also manually change the schedule of existing messages with a statement like +this: + +```sql +update my_message set priority = :priority, time_next = :time_next, epoch = :epoch where id in ::ids and time_acked is null +``` + +This comes in handy if a bunch of messages had chronic failures and got +postponed to the distant future. If the root cause of the problem was fixed, +the application could reschedule them to be delivered as soon as possible. You can +also optionally change the priority and or epoch. Lower priority and epoch values +both increase the relative priority of the message and the back-off is less +aggressive. + +You can also view messages using regular `SELECT` queries against the message table. + +## Known limitations + +Here is a short list of possible limitations/improvements: + +* Proactive scheduling: Upcoming messages can be proactively scheduled for + timely delivery instead of waiting for the next polling cycle. +* Changed properties: Although the engine detects new message tables, it does + not refresh the properties (such as `vt_ack_wait`) of an existing table. +* No explicit rate limiting. +* Usage of MySQL partitioning for more efficient purging. + + diff --git a/content/en/docs/19.0/reference/features/monitoring.md b/content/en/docs/19.0/reference/features/monitoring.md new file mode 100644 index 000000000..c04233f4a --- /dev/null +++ b/content/en/docs/19.0/reference/features/monitoring.md @@ -0,0 +1,42 @@ +--- +title: Monitoring +weight: 8 +--- + +# Current state of monitoring + +There are currently three main ways that a Vitess cluster can be monitored. Depending on your needs, you can use any of the following methods: + +## 1. Vitess status pages + +The status HTML pages of various Vitess components can be accessed by pointing your browser to `http://:/debug/status`. The status pages will often display some basic, but useful, information for monitoring. For example, the status page of a vttablet will show the QPS graph for the past few minutes. + +Viewing a status page can be useful since it works out of the box, but it only provides very basic monitoring capabilities. + +## 2. Pull-based metrics system + +Vitess uses Go’s [expvar package](https://golang.org/pkg/expvar/) to expose various metrics, with the expectation that a user can configure a pull-based metrics system to ingest those metrics. Metrics are published to `http://:/debug/vars` as JSON key-value pairs, which should be easy for any metrics system to parse. + +Scraping Vitess variables is a good way to integrate Vitess into an existing monitoring system, and is useful for building up detailed monitoring dashboards. It is also the officially supported way for monitoring Vitess. + +## 3. Push-based metrics system + +Vitess also includes support for push-based metrics systems via plug-ins. Each Vitess component would need to be run with the `--emit_stats` flag. + +By default, the stats_emit_period is 60s, so each component will push stats to the selected backend every minute. This is configurable via the `--stats_emit_period` flag. + +Vitess has preliminary plug-ins to support OpenTSDB as a push-based metrics backend. + +It should be fairly straightforward to write your own plug-in, if you want to support a different backend. The plug-in package simply needs to implement the `PushBackend` interface of the `stats` package. For an example, you can see the [OpenTSDB plugin](https://github.com/vitessio/vitess/blob/main/go/stats/opentsdb/opentsdb.go). + +Once you’ve written the backend plug-in, you also need to register the plug-in from within all the relevant Vitess binaries. An example of how to do this can be seen in [this pull request](https://github.com/vitessio/vitess/pull/469). + +You can then specify that Vitess should publish stats to the backend that you’re targeting by using the `--stats_backend` flag. + +Connecting Vitess to a push-based metrics system can be useful if you’re already running a push-based system that you would like to integrate into. + +# Monitoring with Kubernetes + +The existing methods for integrating metrics are not supported in a Kubernetes environment by the Vitess team yet, but are on the roadmap for the future. However, it should be possible to get the Prometheus backend working with Kubernetes. + +In the meantime, if you run into issues or have questions, please post on our [Slack](https://vitess.io/slack). diff --git a/content/en/docs/19.0/reference/features/mysql-query-extensions.md b/content/en/docs/19.0/reference/features/mysql-query-extensions.md new file mode 100644 index 000000000..a50f5b873 --- /dev/null +++ b/content/en/docs/19.0/reference/features/mysql-query-extensions.md @@ -0,0 +1,17 @@ +--- +title: MySQL Query Language Extensions +weight: 9 +aliases: [] +--- + +Vitess uses the MySQL [client server protocol](https://dev.mysql.com/doc/internals/en/client-server-protocol.html) and [query language](https://dev.mysql.com/doc/refman/en/language-structure.html). While there are some [limitations and compatibility mismatches](../../compatibility/mysql-compatibility/), Vitess also expands on the MySQL query language for Vitess specific usage. + +## Extensions to the MySQL Query Language + +* [SHOW](../show) has some additional functionality. +* [VEXPLAIN](../../../user-guides/sql/explain-format-vtexplain) is similar to `EXPLAIN` but specifically for Vitess plans +* You can use a special `SELECT` query to see the next value from a sequence: + +```sql +select next value from user_seq; +``` diff --git a/content/en/docs/19.0/reference/features/mysql-replication.md b/content/en/docs/19.0/reference/features/mysql-replication.md new file mode 100644 index 000000000..a7bf9d6bd --- /dev/null +++ b/content/en/docs/19.0/reference/features/mysql-replication.md @@ -0,0 +1,37 @@ +--- +title: Replication +weight: 9 +aliases: ['/docs/reference/row-based-replication/','/docs/reference/vitess-replication/','/docs/reference/mysql-replication/'] +--- + +{{< warning >}} +Vitess requires the use of Row-Based Replication with GTIDs enabled. In addition, Vitess only supports the default `binlog_row_image` of `FULL`. +{{< /warning >}} + +Vitess makes use of MySQL Replication for both high availability and to receive a feed of changes to database tables. This feed is then used in features such as [VReplication](../../vreplication/vreplication/), and to identify schema changes so that caches can be updated. + +## Semi-Sync + +Vitess strongly recommends the use of Semi-synchronous replication for High Availability. The characteristics of semi-sync are replication governed by the [Durability Policy](../../../user-guides/configuration-basic/durability_policy) configured for the keyspace. +Some characteristics are shared by all the policies - + +* Vitess configures the semi-sync timeout to essentially an unlimited number so that it will never fallback to asyncronous replication. This is important to prevent split brain (or alternate futures) in case of a network partition. If we can verify all replicas have stopped replicating, we know the old primary is not accepting writes, even if we are unable to contact the old primary itself. + +* All pre-configured durability policies do not allow tablets of type rdonly to send semi-sync ACKs. This is intentional because rdonly tablets are not eligible to be promoted to primary, so Vitess avoids the case where a rdonly tablet is the single best candidate for election at the time of primary failure. + +Having semi-sync enabled, gives you the property that, in case of primary failure, there is at least one other replica that has every transaction that was ever reported to clients as having completed. You can then wait for [VTOrc](../../../user-guides/configuration-basic/vtorc) to repair it, or ([manually](../../programs/vtctl/shards/#emergencyreparentshard) pick the replica that is farthest ahead in GTID position and promote that to be the new primary. + +Thus, you can survive sudden primary failure without losing any transactions that were reported to clients as completed. In MySQL 5.7+, this guarantee is strengthened slightly to preventing loss of any transactions that were ever **committed** on the original primary, eliminating so-called [phantom reads](http://bugs.mysql.com/bug.php?id=62174). + +On the other hand these behaviors also give a requirement that each shard must have at least 2 tablets with type *replica* (with addition of the primary that can be demoted to type *replica* this gives a minimum of 3 tablets with initial type *replica*). This will allow for the primary to have a semi-sync acker when one of the replica tablets is down for any reason (for a version update, machine reboot, schema swap or anything else). +These requirements will changed based on the durability policy. + +With regard to replication lag, note that this does **not** guarantee there is always at least one replica from which queries will always return up-to-date results. Semi-sync guarantees that at least one replica has the transaction in its relay log, but it has not necessarily been applied yet. The only way Vitess guarantees a fully up-to-date read is to send the request to the primary. + +## Database Schema Considerations + +* Row-based replication requires that replicas have the same schema as the primary, and corruption will likely occur if the column order does not match. Earlier versions of Vitess which used Statement-Based replication recommended applying schema changes on replicas first, and then swapping their role to primary. This method is no longer recommended in favour of the use of Online-DDL. More information can be found [here](../../../user-guides/schema-changes). + +* Using a column of type `FLOAT` or `DOUBLE` as part of a Primary Key is not supported. This limitation is because Vitess may try to execute a query for a value (for example 2.2) which MySQL will return zero results, even when the approximate value is present. + +* It is not recommended to change the schema at the same time a resharding operation is being performed. This limitation exists because interpreting RBR events requires accurate knowledge of the table's schema, and Vitess does not always correctly handle the case that the schema has changed. diff --git a/content/en/docs/19.0/reference/features/recovery.md b/content/en/docs/19.0/reference/features/recovery.md new file mode 100644 index 000000000..0be939330 --- /dev/null +++ b/content/en/docs/19.0/reference/features/recovery.md @@ -0,0 +1,186 @@ +--- +title: Point In Time Recovery +weight: 17 +aliases: ['/docs/recovery/pitr','/docs/reference/pitr/'] +--- + +## Point in Time Recovery + +Vitess supports incremental backup and recoveries, AKA point in time recoveries. `v17` offers restore-to-position functionality, and `v18` is slated to support restore-to-timestamp functionality in addition. + +Point in time recoveries are based on full and incremental backups. It is possible to recover a database to a position that is _covered_ by some backup. + +See [Backup Types](../../../user-guides/operating-vitess/backup-and-restore/overview/#backup-types) and [Restore Types](../../../user-guides/operating-vitess/backup-and-restore/overview/#restore-types) for an overview of incremental backups and restores. + +See the user guides for how to [Create an Incremental Backup](../../../user-guides/operating-vitess/backup-and-restore/creating-a-backup/#create-an-incremental-backup-with-vtctl) and how to [Restore to a position](../../../user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore/#restore-to-a-point-in-time). + +### Supported Databases +- MySQL 5.7, 8.0 + +### Notes + +This functionality replaces a legacy functionality, based on binlog servers and transient binary logs. + +## Point in Time Recovery: legacy functionality based on binlog server + +### Supported Databases +- MySQL 8.0 + +### Introduction + +The Point in Time Recovery feature in Vitess enables recovery of data to a specific point time (timestamp). There can be multiple recovery requests active at the same time. It is possible to recover across sharding actions, i.e. you can recover to a time when there were two shards even though at present there are four. + +Point in Time Recovery leverages two Vitess features: + +1. The use of `SNAPSHOT` keyspaces for recovery of the last backup before a requested specific timestamp to restore to. +2. Integration with a binlog server to allow vttablet to apply binary logs from the recovered backup up to the specified timestamp. + +### Use cases + +- Accidental deletion of data, e.g. dropping a table by mistake, running an UPDATE or DELETE with an incorrect WHERE clause, etc. +- Corruption of data due to application bugs. +- Corruption of data due to MySQL bugs or underlying hardware (e.g. storage) problems. + +### Preconditions + +- There should be a Vitess backup taken before the desired point in time. +- There should be continuous binlogs available from the backup time to the desired point in time. +- This feature is tested using [Ripple](https://github.com/google/mysql-ripple) as the binlog server. However, it should be possible to use a MySQL instance as source for the binlogs as well. + +### Example usage + +To use this feature, you need a usable backup of Vitess data and continuous binlogs. + +Here is how you can create a backup. + +```sh +$ vtctldclient --server : Backup zone1-101 +``` + +Here `zone1-101` is the tablet alias of a replica tablet in the shard that you +want to back up. Note that you can also use `vtctldclient BackupShard` to just +specify a keyspace and shard, and have Vitess choose the tablet to run the +backup for you, instead of having to specify the tablet alias explicitly. + +To maintain continuous binlogs, you need to have a binlog server pointing to +the primary (or a replica, assuming that the replica is also maintaining its +own binlogs, which is the default Vitess configuration). You can use +[Ripple](https://github.com/google/mysql-ripple) as a binlog server, although +there are other options; and you could use an existing MySQL server as well. + +If you use Ripple, you will need to configure it yourself, and ensure you take +care of the following: + + - You should have a highly available binlog server setup. If the binlog + server goes down, you need to ensure that it is back up and able + to synchronize the MySQL binary logs from its upstream MySQL server + before the upstream server deletes the current binlog. If you + do not do this, you will end up with gaps in your binlogs, which + could make restoring to a specific point in time impossible. Make + sure that you setup your operational and monitoring procedures + accordingly. + - The binlog files should be safely kept at some reliable and recoverable + location (e.g. AWS S3, remote file storage). + +Once the above is done, you can proceed with doing a recovery. + +#### Recovery Procedure + +First, you need to create a `SNAPSHOT` keyspace with a `base-keyspace` +pointing to the original keyspace you are recovering the backup of. +This can be done by using following: + +```sh +$ vtctldclient --server : CreateKeyspace --type=SNAPSHOT --base-keyspace=originalks --snapshot-time=2020-07-17T18:25:20Z restoreks +``` + + Here: + - `originalks` is the base keyspace, i.e. the keyspace we took a backup of, + and are trying to recover. + - `snapshot-time` is the timestamp of the point in time to we want to recover + to. Note the use of the `Z` in the timestamp, indicating it is expressed + in UTC. + - `restoreks` is the name of recovery keyspace, i.e. the keyspace to which + we are restoring our backup. + + Next, you can launch the vttablet, which as part of vttablet's normal + initialization procedure will look for a backup to restore. It will + detect the meta-information you added on the keyspace topology node + when creating the keyspace above. It will then use that information + to restore the last backup earlier than the timestamp provided for the + specific shard the vttablet is in. + + Here are the command line arguments vttablet uses in this + process. You may already be using some of these as part of your + normal vttablet initialization parameters (e.g. if you are using the + Vitess K8s operator): + + - `--init_keyspace restoreks` - here `restoreks` is the recovery keyspace + name which we created earlier + - `--init_db_name_override vt_originalks` - here `vt_originalks` is the + name of the original underlying database for the keyspace that you backed + up and want to restore. Usually, this takes the form of `vt_` prepended + to the keyspace name. However, the original underlying database could + also have been using an `--init_db_name_override` directive of its own, + and this value should then be set to match that. + - `--init_shard 0` - here `0` is the shard name (or range) which we want + to recover. + - `--binlog_host x.x.x.x` - hostname or IP address of binlog server. + - `--binlog_port XXXX` - TCP port of binlog server. + - `--binlog_user XXXX` - username to access binlog server. + - `--binlog_password YYYY` - password to access binlog server. + - `--pitr_gtid_lookup_timeout duration` - See below for details. + +And then, depending on your backup storage implementation, you can use a +variety of flags: + + - `--backup_storage_implementation file` - for plain file backup type. + If you use this option, you will also need to specify: + - `--file_backup_storage_root` - with a path pointing to your backup + storage location. + - `--backup_storage_implementation s3` - for backing up to S3. If you + use this option, you may need additional flags like: + - `--s3_backup_aws_region` + - `--s3_backup_storage_bucket` + - `--s3_backup_storage_root` + - There are more `--backup_storage_implementation` options like `gcs` and + others. + +{{< warning >}} +When using the file backup storage engine the backup storage root path must be on shared storage to provide a global view of backups to all vitess components. +{{< /warning >}} + +You will also probably want to use other flags for backup and restore like: + + - `--backup_engine_implementation xtrabackup` - Use Percona Xtrabackup to + take online backups. Without this flag, the mysql instance on the replica + being backed up will be shut down during the backup. + - `--backup_storage_compress true` - gzip compress the backup (default is + true). + +You need to be consistent in your use of these flags for backup and restore. + +Once the restore of the last backup earlier than the `snapshot-time` timestamp +is completed, the vttablet proceeds to use the `binlog_*` parameters to +connect to the binlog server and then apply all binlog events from the time +of the backup until the timestamp provided. + +Since the last backup for each shard making up the keyspace could be taken at +different points in time, the amount of time that it takes to apply these events +may differ between restores of different shards in the keyspace. + +Note that to restore to the specified `snapshot-time` timestamp, vttablet needs +to find the GTID corresponding to the last event before this timestamp from +the binlog server. This is an expensive operation and may take some time. By +default the timeout for this operation is one minute (1m). This can be changed +by setting the vttablet `--pitr_gtid_lookup_timeout` flag. + +VTGate will automatically exclude tablets belonging to snapshot keyspaces from +query routing unless they are specifically addressed using `USE restoreks` +or by using queries of the form `SELECT ... FROM restoreks.table`. + +The base keyspace's vschema will be copied over to the new snapshot keyspace +as a default. If desired this can be overwritten by the user. Care needs to +be taken to set `require_explicit_routing` to true when modifying a snapshot +keyspace's vschema, or you will bypass the VTGate routing safety feature +described above. diff --git a/content/en/docs/19.0/reference/features/schema-management.md b/content/en/docs/19.0/reference/features/schema-management.md new file mode 100644 index 000000000..b425e6293 --- /dev/null +++ b/content/en/docs/19.0/reference/features/schema-management.md @@ -0,0 +1,118 @@ +--- +title: Schema Management +weight: 16 +aliases: ['/docs/schema-management/','/docs/user-guides/schema-management/','/docs/reference/schema-management/'] +--- + +Using Vitess requires you to work with two different types of schemas: + +1. The MySQL database schema. This is the schema of the individual MySQL instances. +2. The [VSchema](../vschema), which describes all the keyspaces and how they're sharded. + +The workflow for the `VSchema` is as follows: + +1. Apply the `VSchema` for each keyspace using the `ApplyVschema` command. This saves the VSchemas in the global topology service. +2. Execute `RebuildVSchemaGraph` for each cell (or all cells). This command propagates a denormalized version of the combined VSchema to all the specified cells. The main purpose for this propagation is to minimize the dependency of each cell from the global topology. The ability to push a change to only specific cells allows you to canary the change to make sure that it's good before deploying it everywhere. + +This document describes the [`vtctl`](../../../reference/programs/vtctl/) commands that you can use to [review](#reviewing-your-schema) or [update](#changing-your-schema) your schema in Vitess. + +Note that this functionality is not recommended for long-running schema changes. It is recommended to use a tool such as [`pt-online-schema-change`](https://www.percona.com/doc/percona-toolkit/LATEST/pt-online-schema-change.html) or [`gh-ost`](https://github.com/github/gh-ost) instead. + + +## Reviewing your schema + +This section describes the following vtctl commands, which let you look at the schema and validate its consistency across tablets or shards: + +* [GetSchema](#getschema) +* [ValidateSchemaShard](#validateschemashard) +* [ValidateSchemaKeyspace](#validateschemakeyspace) +* [GetVSchema](#getvschema) +* [GetSrvVSchema](#getsrvvschema) + +### GetSchema + +The [GetSchema](../../programs/vtctl/schema-version-permissions#getschema) command displays the full schema for a tablet or a subset of the tablet's tables. When you call `GetSchema`, you specify the tablet alias that uniquely identifies the tablet. The `` argument value has the format `-`. + +**Note**: You can use the [`vtctl ListAllTablets`](../../../reference/programs/vtctl/#listalltablets) command to retrieve a list of tablets in a cell and their unique IDs. + +The following example retrieves the schema for the tablet with the unique ID test-000000100: + +``` sh +GetSchema test-000000100 +``` + +### ValidateSchemaShard + +The [`ValidateSchemaShard`](../../../reference/programs/vtctl/#validateschemashard) command confirms that for a given keyspace, all of the replica tablets in a specified shard have the same schema as the primary tablet in that shard. When you call `ValidateSchemaShard`, you specify both the keyspace and the shard that you are validating. + +The following command confirms that the primary and replica tablets in shard `0` all have the same schema for the `user` keyspace: + +``` sh +ValidateSchemaShard user/0 +``` + +### ValidateSchemaKeyspace + +The [`ValidateSchemaKeyspace`](../../../reference/programs/vtctl/#validateschemakeyspace) command confirms that all of the tablets in a given keyspace have the the same schema as the primary tablet on shard `0` in that keyspace. Thus, whereas the `ValidateSchemaShard` command confirms the consistency of the schema on tablets within a shard for a given keyspace, `ValidateSchemaKeyspace` confirms the consistency across all tablets in all shards for that keyspace. + +The following command confirms that all tablets in all shards have the same schema as the primary tablet in shard 0 for the user keyspace: + +``` sh +ValidateSchemaKeyspace user +``` + +### GetVSchema + +The [`GetVSchema`](../../../reference/programs/vtctl/#getvschema) command displays the global VSchema for the specified keyspace. + +### GetSrvVSchema + +The [`GetSrvVSchema`](../../../reference/programs/vtctl/#getsrvvschema) command displays the combined VSchema for a given cell. + +## Changing your schema + +This section describes the following commands: + +* [ApplySchema](#applyschema) +* [ApplyVSchema](#applyvschema) +* [RebuildVSchemaGraph](#rebuildvschemagraph) + +### ApplySchema + +Vitess offers [managed schema migration](../../../user-guides/schema-changes/managed-online-schema-changes/), and notably supports online schema migrations (aka Online DDL), transparently to the user. Vitess Online DDL offers: + +* Non-blocking migrations +* Migrations are asyncronously auto-scheduled, queued and executed by tablets +* Migration state is trackable +* Migrations are cancellable +* Migrations are retry-able +* Lossless, [revertible migrations](../../../user-guides/schema-changes/revertible-migrations/) +* Support for [declarative migrations](../../../user-guides/schema-changes/declarative-migrations/) +* Support for [postponed migrations](../../../user-guides/schema-changes/postponed-migrations/) +* Support for [failover agnostic migrations](../../../user-guides/schema-changes/recoverable-migrations/) +* Support for [concurrent migrations](../../../user-guides/schema-changes/concurrent-migrations/) + +The [ApplySchema](../../../reference/programs/vtctl/schema-version-permissions/#applyschema) command applies a schema change to the specified keyspace on all shards. The command format is: `ApplySchema -- {--sql= || --sql_file=} ` + +Further reading: + +* [Making schema changes](../../../user-guides/schema-changes/) +* [Managed schema changes](../../../user-guides/schema-changes/managed-online-schema-changes/) +* [DDL strategies](../../../user-guides/schema-changes/ddl-strategies/) + +#### Permitted schema changes + +The `ApplySchema` command supports these commands: + +* `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `CREATE VIEW`, `ALTER VIEW`, `DROP VIEW` in Online DDL +* In addition, `CREATE INDEX`, `DROP INDEX`, `RENAME TABLE`, in non Online DDL + +`ApplySchema` does not support creation or modifications of stored routines, including functions, procedures, triggers, and events. + +### ApplyVSchema + +The [`ApplyVSchema`](../../../reference/programs/vtctl/#applyvschema) command applies the specified VSchema to the keyspace. The VSchema can be specified as a string or in a file. + +### RebuildVSchemaGraph + +The [`RebuildVSchemaGraph`](../../../reference/programs/vtctl/#rebuildvschemagraph) command propagates the global VSchema to a specific cell or the list of specified cells. diff --git a/content/en/docs/19.0/reference/features/schema-routing-rules.md b/content/en/docs/19.0/reference/features/schema-routing-rules.md new file mode 100644 index 000000000..ede10a3de --- /dev/null +++ b/content/en/docs/19.0/reference/features/schema-routing-rules.md @@ -0,0 +1,178 @@ +--- +title: Schema Routing Rules +weight: 15 +aliases: ['/docs/schema-management/routing-rules/','/docs/reference/schema-routing-rules/'] +--- + +The Vitess routing rules feature is a powerful mechanism for directing query traffic to the right keyspaces, shards, and tablet types in +[Vitess Gateways](../../../concepts/vtgate/) (`vtgate`). Their primary usage today is for the following use case: + +* **Routing traffic during data migrations**: during e.g. [`MoveTables`](../../vreplication/movetables/) and + [`Reshard`](../../vreplication/reshard/) operations, routing rules dictate where to send reads and writes. These routing rules are managed + automatically by [VReplication](../../vreplication/vreplication/). You can see an example of their usage in the + [MoveTables](../../../user-guides/migration/move-tables/) user guide. + +Understanding the routing rules can help you debug migration related issues as well as provide you with another powerful tool as +you operate Vitess. + +## Viewing Routing Rules + +The routing rules are global and can be viewed using the [`GetRoutingRules` client command](../../programs/vtctldclient/vtctldclient_getroutingrules/). + +## Updating Routing Rules + +You can update the routing rules using the [`ApplyRoutingRules` client command](../../programs/vtctldclient/vtctldclient_applyroutingrules/). + +## Syntax + +Routing rules are managed using the JSON format. Here's an example, using the routing rules that are put in place by `MoveTables` +in the [local examples](../../../get-started/local/) where the `customer` and `corder` tables are being moved from the `commerce` +keyspace to the `customer` keyspace and we have not yet switched traffic from the `commerce` keyspace to the `customer` keyspace — so all +traffic, regardless of which keyspace a client uses, are sent to the `commerce` keyspace: +```json +$ vtctldclient --server=localhost:15999 GetRoutingRules +{ + "rules": [ + { + "from_table": "customer.customer", + "to_tables": [ + "commerce.customer" + ] + }, + { + "from_table": "commerce.corder@replica", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "customer.customer@rdonly", + "to_tables": [ + "commerce.customer" + ] + }, + { + "from_table": "commerce.corder@rdonly", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "corder@replica", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "commerce.customer@replica", + "to_tables": [ + "commerce.customer" + ] + }, + { + "from_table": "commerce.customer@rdonly", + "to_tables": [ + "commerce.customer" + ] + }, + { + "from_table": "customer.corder@replica", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "customer.corder@rdonly", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "customer.customer@replica", + "to_tables": [ + "commerce.customer" + ] + }, + { + "from_table": "customer.corder", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "corder@rdonly", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "customer@replica", + "to_tables": [ + "commerce.customer" + ] + }, + { + "from_table": "customer@rdonly", + "to_tables": [ + "commerce.customer" + ] + }, + { + "from_table": "corder", + "to_tables": [ + "commerce.corder" + ] + }, + { + "from_table": "customer", + "to_tables": [ + "commerce.customer" + ] + } + ] +} +``` + +## When Routing Rules Are Applied + +In the above example, we send all query traffic for the `customer` and `corder` tables to the `commerce` keyspace regardless of how +the client specifies the database/schema and table qualifiers. There is, however, one important exception and that is when the client +explicitly requests the usage of a specific shard, also known as "shard targeting". For example, if the client specifies the database +as `customer:0` or `customer:0@replica` then the query will get run against that shard in the customer keyspace. + +{{< warning >}} +You should exercise _extreme_ caution when executing ad-hoc *write* queries during this time as you may think that you're deleting data +from the target keyspace, that is as of yet unused, when in reality you're deleting it from the source keyspace that is currently +serving production traffic. +{{}} + +{{< info >}} +You can leverage shard targeting to perform ad-hoc *read-only* queries against the target and source keyspace/shards to perform any +additional data validation or checks that you want (beyond [`VDiff`](../../vreplication/vdiff/)). You can also use this shard targeting +to see how your data is distributed across the keyspace's shards. +{{}} + +## Additional Details + +There are some key details to keep in mind if you will be creating and managing your own custom routing rules. +- The `to_tables` field must contain only one entry and the table name must be fully qualified. + +- If the `from_table` is qualified by a keyspace, then a query that references that table will get redirected to the corresponding target table. The reference need not be explicit. For example, if you are connected to the `customer` keyspace, then an unqualified reference to the `customer` table is interpreted as a qualified reference to `customer.customer`. + +- You may further add a tablet type to the `from_table` field using the `@` syntax seen in the example above. If so, only queries that target that tablet type will get redirected. Although you can qualify a table by its keyspace in a query, there is no equivalent syntax for specifying the tablet type. The only way to choose a tablet type is through the `use` statement, like `use customer@replica`, or by specifying it in the connection string. + +- The more specific rules supercede the less specific one. For example, `customer.customer@replica` is chosen over `customer.customer` if the current tablet type is a `replica`. + +- If the `to_tables` have special characters that need escaping, you can use the mysql backtick syntax to do so. As for the `from_tables`, the table name should *not* be escaped. Instead, you should just concatenate the table with the keyspace without the backticks. In the following example, we are redirecting the `b.c` table to the `c.b` table in keyspace `a`: + ``` json + { + "rules": [ + { + "from_table": "a.b.c", + "to_tables": [ + "a.`c.b`" + ] + } + ] + } + ``` diff --git a/content/en/docs/19.0/reference/features/schema-tracking.md b/content/en/docs/19.0/reference/features/schema-tracking.md new file mode 100644 index 000000000..61ff0bfb5 --- /dev/null +++ b/content/en/docs/19.0/reference/features/schema-tracking.md @@ -0,0 +1,26 @@ +--- +title: Schema Tracking +weight: 16 +aliases: ['/docs/reference/schema-tracking/'] +--- + +VTGate natively tracks table schema using two different methods: schema tracking and VSchema. Using the VSchema, users are allowed to provide an authoritative list of columns which is then used to enhance query planning. If none is provided, VTGate uses its schema tracking feature. + +When using schema tracking, VTGate keeps an authoritative list of columns on all tables. The following query set can be planned: + +1. `SELECT *` cross-shard queries that need evaluation at the VTGate level. +2. Queries that are not able to resolve columns dependencies. For instance: queries with no table qualifier in the projection/filter list. +3. Evaluation improvement in Aggregations, Group By, Having, Limit, etc. clauses that require processing of records at VTGate level. VTGate will not require `weight_string()` value for the evaluation and can compare the values directly. + +If schema tracking happened to be disabled and no authoritative list of columns is provided, a set of queries will not be supported by VTGate due to a lack of information on the underlying tables/columns. + +More information on this feature can be found in [this blog post](https://vitess.io/blog/2022-01-11-schema-tracking/). + +## VTGate + +Schema tracking is enabled in VTGate with the flag `--schema_change_signal`, defaults to `true`. When enabled, VTGate listens for schema changes from VTTablet. +A change triggers a `GetSchema` rpc call to VTTablet to retrieve the stored schema. + +## VTTablet + +Schema tracking is enabled in VTTablet with the flag `--queryserver-config-schema-change-signal`, defaults to `true`. When enabled, VTTablet sends schema changes to VTGate when a DDL query executes. Additionally, VTTablet regularly checks for schema changes at a specified interval, which can be adjusted using the `--queryserver-config-schema-reload-time` flag. The default interval is set to 30 minutes. diff --git a/content/en/docs/19.0/reference/features/sharding.md b/content/en/docs/19.0/reference/features/sharding.md new file mode 100644 index 000000000..0501484be --- /dev/null +++ b/content/en/docs/19.0/reference/features/sharding.md @@ -0,0 +1,99 @@ +--- +title: Sharding +description: Shard widely, shard often. +weight: 1 +aliases: ['/docs/sharding/','/user-guide/sharding.html','/docs/reference/sharding/'] +--- + +Sharding is a method of horizontally partitioning a database to store data across two or more database servers. This document explains how sharding works in Vitess and the types of sharding that Vitess supports. + +## Overview + +A keyspace in Vitess can be sharded or unsharded. An unsharded keyspace maps directly to a MySQL database. If sharded, the rows of the keyspace are partitioned into different databases of identical schema. + +For example, if an application's "user" keyspace is split into two shards, each shard contains records for approximately half of the application's users. Each single user's information however, is stored in only one shard. + +Note that sharding is orthogonal to (MySQL) replication. A Vitess shard typically contains one MySQL primary and many MySQL replicas. The primary handles write operations, while replicas handle read-only traffic, batch processing operations, and other tasks. Each MySQL instance within the shard should have the same data, excepting some replication lag. + +### Supported Operations + +Vitess supports the following types of sharding operations: + +* **Horizontal sharding:** Splitting or merging shards in a sharded keyspace +* **Vertical sharding:** Moving tables from an unsharded keyspace to + a different keyspace. + +With these features, you can start with a single keyspace that contains all of your data (in multiple tables). As your database grows, you can move tables to different keyspaces (vertical split) and shard some or all of those keyspaces (horizontal split) without any real downtime for your application. + +## Sharding scheme + +Vitess allows you to choose the type of sharding scheme by the choice of your Primary Vindex for the tables of a shard. Once you have chosen the Primary Vindex, you can choose the partitions depending on how the resulting keyspace IDs are distributed. + +Vitess calculates the sharding key or keys for each query and then routes that query to the appropriate shards. For example, a query that updates information about a particular user might be directed to a single shard in the application's "user" keyspace. On the other hand, a query that retrieves information about several products might be directed to one or more shards in the application's "product" keyspace. + +### Key Ranges and Partitions + +Vitess uses key ranges to determine which shards should handle any particular query. + +* A **key range** is a series of consecutive keyspace ID values. It has starting and ending values. A key falls inside the range if it is equal to or greater than the start value and strictly less than the end value. +* A **partition** represents a set of key ranges that covers the entire space. + +When building the serving graph for a sharded keyspace, Vitess ensures that each shard is valid and that the shards collectively constitute a full partition. In each keyspace, one shard must have a key range with an empty start value and one shard, which could be the same shard, must have a key range with an empty end value. + +* An empty start value represents the lowest value, and all values are greater than it. +* An empty end value represents a value larger than the highest possible value, and all values are strictly lower than it. + +Vitess always converts sharding keys to a left-justified binary string for computing a shard. This left-justification makes the right-most zeroes insignificant and optional. Therefore, the value `0x80` is the middle value for sharding keys. So, in a keyspace with two shards, sharding keys that have a binary value lower than 0x80 are assigned to the first shard. Keys with a binary value equal to or higher than 0x80 are assigned to the other shard. + +Several sample key ranges are shown below: + +``` sh +Start=[], End=[]: Full Key Range +Start=[], End=[0x80]: Lower half of the Key Range. +Start=[0x80], End=[]: Upper half of the Key Range. +Start=[0x40], End=[0x80]: Second quarter of the Key Range. +Start=[0xFF00], End=[0xFF80]: Second to last 1/512th of the Key Range. +``` + +Two key ranges are consecutive if the end value of one range equals the start value of the other range. + +### Shard Names + +A shard's name identifies the start and end of the shard's key range, printed in hexadecimal and separated by a hyphen. For instance, if a shard's key range is the array of bytes beginning with [ 0x80 ] and ending, noninclusively, with [ 0xc0], then the shard's name is `80-c0`. + +Using this naming convention, the following four shards would be a valid full partition: + +* -40 +* 40-80 +* 80-c0 +* c0- + +Shards do not need to handle the same size portion of the key space. For example, the following five shards would also be a valid full partition, possibly with a highly uneven distribution of keys. + +* -80 +* 80-c0 +* c0-dc00 +* dc00-dc80 +* dc80- + +## Resharding + +Resharding describes the process of updating the sharding scheme for a keyspace and dynamically reorganizing data to match the new scheme. During resharding, Vitess copies, verifies, and keeps data up-to-date on new shards while the existing shards continue to serve live read and write traffic. When you're ready to switch over, the migration occurs with only a few seconds of read-only downtime. During that time, existing data can be read, but new data cannot be written. + +The table below lists the sharding (or resharding) processes that you would typically perform for different types of requirements: + +Requirement | Action +----------- | ------ +Uniformly increase read capacity | Add replicas or split shards +Uniformly increase write capacity | Split shards +Reclaim overprovisioned resources | Merge shards and/or keyspaces +Increase geo-diversity | Add new cells and replicas +Cool a hot tablet | For read access, add replicas or split shards. For write access, split shards. + +### Additional Tools and Processes + +Vitess provides the following tools to help manage range-based shards: + +* The [vtctl GenerateShardRanges](../../../reference/programs/vtctl/shards/#generateshardranges) command-line tool supports generating shard ranges based on the provided number of shards. +* There are additional [Shard specific vtctl](../../../reference/programs/vtctl/shards) command-line tools. +* Client APIs account for sharding operations. diff --git a/content/en/docs/19.0/reference/features/show.md b/content/en/docs/19.0/reference/features/show.md new file mode 100644 index 000000000..88fb37807 --- /dev/null +++ b/content/en/docs/19.0/reference/features/show.md @@ -0,0 +1,107 @@ +--- +title: SHOW extensions +weight: 9 +aliases: [] +--- + +In Vitess, `SHOW` has been extended with additional functionality. + +### SHOW Statements + +Vitess supports the following additional SHOW statements: + +* `SHOW GLOBAL GTID_EXECUTED [FROM ]` -- retrieves the global gtid_executed status variable from each shard in the keyspace either selected or provided in the query. +```shell +Example Output for customer keyspace: ++----------+-------------------------------------------+-------+ +| db_name | gtid_executed | shard | ++----------+-------------------------------------------+-------+ +| customer | e9148eb0-a320-11eb-8026-98af65a6dc4a:1-43 | 80- | +| customer | e0f64aca-a320-11eb-9be4-98af65a6dc4a:1-43 | -80 | ++----------+-------------------------------------------+-------+ +``` + +* `SHOW KEYSPACES` -- A list of keyspaces available. +```shell +Example Output: ++----------+ +| Database | ++----------+ +| commerce | +| customer | ++----------+ +``` + +* `SHOW VITESS_REPLICATION_STATUS [LIKE ""]` (**Experimental; 12.0+**) -- Shows the Replication (_not_ [VReplication](../../vreplication/vreplication/)) health for the Vitess deployment. It returns a row for each `REPLICA` and `RDONLY` tablet in the topology -- with support for filtering by Keyspace/Shard using a `LIKE` clause -- providing relevant health and status information, including the current [tablet throttler](../tablet-throttler/) status. +```shell +Example Output: ++----------+-------+------------+------------------+--------------+--------------------+-------------------------------------------------------------------------+----------------+-----------------------------------------+ +| Keyspace | Shard | TabletType | Alias | Hostname | ReplicationSource | ReplicationHealth | ReplicationLag | ThrottlerStatus | ++----------+-------+------------+------------------+--------------+--------------------+-------------------------------------------------------------------------+----------------+-----------------------------------------+ +| commerce | 0 | REPLICA | zone1-0000000101 | 52030e360852 | 52030e360852:17100 | {"EventStreamRunning":"Yes","EventApplierRunning":"Yes","LastError":""} | 0 | {"state":"OK","load":0.00,"message":""} | +| commerce | 0 | RDONLY | zone1-0000000102 | 52030e360852 | 52030e360852:17100 | {"EventStreamRunning":"Yes","EventApplierRunning":"Yes","LastError":""} | 0 | {"state":"OK","load":0.00,"message":""} | ++----------+-------+------------+------------------+--------------+--------------------+-------------------------------------------------------------------------+----------------+-----------------------------------------+ +``` + +* `SHOW VITESS_SHARDS` -- A list of shards that are available. +```shell +Example Output: ++--------------+ +| Shards | ++--------------+ +| commerce/0 | +| customer/-80 | +| customer/80- | ++--------------+ +``` + +* `SHOW VITESS_TABLETS` -- Information about the current Vitess tablets such as the keyspace, key ranges, tablet type, hostname, and status. +```shell +Example Output: ++-------+----------+-------+------------+---------+------------------+------------+----------------------+ +| Cell | Keyspace | Shard | TabletType | State | Alias | Hostname | PrimaryTermStartTime | ++-------+----------+-------+------------+---------+------------------+------------+----------------------+ +| zone1 | commerce | 0 | PRIMARY | SERVING | zone1-0000000100 | | 2021-04-22T04:10:29Z | +| zone1 | commerce | 0 | REPLICA | SERVING | zone1-0000000101 | | | +| zone1 | commerce | 0 | RDONLY | SERVING | zone1-0000000102 | | | +| zone1 | customer | -80 | PRIMARY | SERVING | zone1-0000000300 | | 2021-04-22T04:12:23Z | +| zone1 | customer | -80 | REPLICA | SERVING | zone1-0000000301 | | | +| zone1 | customer | -80 | RDONLY | SERVING | zone1-0000000302 | | | +| zone1 | customer | 80- | PRIMARY | SERVING | zone1-0000000400 | | 2021-04-22T04:12:23Z | +| zone1 | customer | 80- | REPLICA | SERVING | zone1-0000000401 | | | +| zone1 | customer | 80- | RDONLY | SERVING | zone1-0000000402 | | | ++-------+----------+-------+------------+---------+------------------+------------+----------------------+ +``` + +* `SHOW VSCHEMA TABLES` -- A list of tables available in the current keyspace's vschema. +```shell +Example Output for customer keyspace: ++----------+ +| Tables | ++----------+ +| corder | +| customer | +| dual | ++----------+ +``` + +* `SHOW VSCHEMA VINDEXES` -- Information about the current keyspace's vindexes such as the keyspace, name, type, params, and owner. Optionally supports an "ON" clause with a table name. +```shell +Example Output: ++----------+------+------+--------+-------+ +| Keyspace | Name | Type | Params | Owner | ++----------+------+------+--------+-------+ +| customer | hash | hash | | | ++----------+------+------+--------+-------+ +``` + +* `SHOW VITESS_THROTTLER STATUS` -- shows status for all tablet throttlers in current keyspace +```shell +Example Output: ++-------+---------+-----------+ +| shard | enabled | threshold | ++-------+---------+-----------+ +| -80 | 1 | 1.5 | +| 80- | 1 | 1.5 | ++-------+---------+-----------+ +``` diff --git a/content/en/docs/19.0/reference/features/tablet-throttler.md b/content/en/docs/19.0/reference/features/tablet-throttler.md new file mode 100644 index 000000000..67c73399d --- /dev/null +++ b/content/en/docs/19.0/reference/features/tablet-throttler.md @@ -0,0 +1,381 @@ +--- +title: Tablet throttler +weight: 21 +aliases: ['/docs/user-guides/tablet-throttler/','/docs/reference/tablet-throttler/'] +--- + +VTTablet runs a cooperative throttling service. This service probes the shard's MySQL topology and observes health, measure by replication lag, or by another metric delivered by custom query, on servers. The throttler is derived from GitHub's [freno](https://github.com/github/freno). + +## Why throttler: maintaining shard health via low replication lag + +Vitess uses MySQL with asynchronous or semi-synchronous replication. In these modes, each shard has a primary instance that applies changes and logs them to the binary log. The replicas for that shard will get binary log entries from the primary, potentially acknowledge them (if semi-synchronous replication is enabled), and apply them. A running replica normally applies the entries as soon as possible, unless it is stopped or configured to delay. However, if the replica is busy, then it may not have the resources to apply events in a timely fashion, and can therefore start lagging. For example, if the replica is serving traffic, it may lack the necessary disk I/O or CPU to avoid lagging behind the primary. + +Maintaining low replication lag is important in production for two reasons: + +- A lagging replica may not be representative of the data on the primary. Reads from the replica reflect data that is not consistent with the data on the primary. This is noticeable on web services following read-after-write from the replica, and this can produce results not reflecting the write. +- An up-to-date replica makes for a good failover experience. If all replicas are lagging, then a failover process must choose between waiting for a replica to catch up or losing data. + +Some common database operations include mass writes to the database, including the following: + +- Online schema migrations duplicating entire tables +- Mass population of columns, such as populating the new column with derived values following an `ADD COLUMN` migration +- Purging of old data +- Purging of tables as part of safe table `DROP` operation + +Other operations include mass reads from the database: + +- An ETL reading content of entire tables +- VReplication scanning an entire keyspace data and binary logs + +These operations can easily incur replication lag. However, these operations are typically not time-limited. It is possible to rate-limit them to reduce database load. + +This is where a throttler becomes useful. A throttler can detect when replication lag is low, a cluster is healthy, and operations can proceed. It can also detect when replication lag is high and advise applications to withhold the next operation. + +Applications are expected to break down their tasks into small sub-tasks. For example, instead of deleting `1,000,000` rows, an application should only delete `50` at a time. Between these sub-tasks, the application should check in with the throttler. + +The throttler is only intended for use with operations such as the above mass write/read cases. It should not be used for ongoing, normal OLTP queries. + +## Throttler overview + +Each `vttablet` runs an internal throttler service, and provides API endpoints to the throttler. Each tablet, including the primary, measures its own "self" health, discussed later. + +### Cluster health: + +In addition, the primary tablet is responsible for the overall health of the cluster/shard: + +- The throttler confirms it is still the primary tablet for its shard. +- Every `10sec`, the throttler uses the topology server to refresh the shard's tablets list. +- The throttler probes all `REPLICA` tablets (or other types of tablets, see [Configuration](#configuration)) for their own throttler metrics. This is done via gRPC. + - The throttler begins in dormant probe mode. As long as no application or client is actually looking for metrics, it probes the servers at multi-second intervals. + - When applications check for throttle advice, the throttler begins probing servers in subsecond intervals. It reverts to dormant probe mode if no requests are made in the duration of `1min`. +- The throttler aggregates the last probed values from all relevant tablets. This is _the cluster's metric_. + +The cluster's metric is only as accurate as the following metrics: + +- The probe interval +- The heartbeat injection interval +- The aggregation interval + +The error margin equals approximately the sum of the above values, plus additional overhead. The defaults for these intervals are as follows: + ++ Probe interval: `100ms` ++ Aggregation interval: `100ms` ++ Heartbeat interval: `250ms` + +The user may override the heartbeat interval by sending `-heartbeat_interval` flag to `vttablet`. + +Thus, the aggregated interval can be off, by default, by some `500ms`. This makes it inaccurate for evaluations that require high resolution lag evaluation. This resolution is sufficient for throttling purposes. + +### Self health + +Each tablet runs a local health check against its backend database, again in the form of evaluating replication lag from `_vt.heartbeat`. Intervals are identical to the cluster health interval illustrated above. + +### Response codes + +The throttler allows clients and applications to `check` for throttle advice. The check is an `HTTP` request, `HEAD` method, or `GET` method. Throttler returns one of the following HTTP response codes as an answer: + +- `200` (OK): The application may write to the data store. This is the desired response. +- `404` (Not Found): The check contains an unknown metric name. This can take place immediately upon startup or immediately after failover, and should resolve within 10 seconds. +- `417` (Expectation Failed): The requesting application is explicitly forbidden to write. The throttler does not implement this at this time. +- `429` (Too Many Requests): Do not write. A normal, expected state indicating there is replication lag. This is the hint for applications or clients to withhold writes. +- `500` (Internal Server Error): An internal error has occurred. Do not write. + +Normally, apps will see either `200` or `429`. An app should only ever proceed to write to the database when it receives a `200` response code. + +The throttler chooses the response by comparing the replication lag with a pre-defined _threshold_. If the lag is lower than the threshold, response can be `200` (OK). If the lag is higher than the threshold, the response would be `429` (Too Many Requests). + +The throttler only collects and evaluates lag on a set of predefined tablet types. By default, this tablet type set is `REPLICA`. See [Configuration](#configuration). + +When the throttler sees no relevant replicas in the shard, it allows writes by responding with `HTTP 200 OK`. + +## Custom metrics & queries + +The default behavior is to measure replication lag and throttle based on that lag. Vitess allows the user to use custom metrics and thresholds for throttling. + +Vitess only supports gauges for custom metrics: the user may define a query which returns a gauge value, an absolute metric by which Vitess can throttle. See [#Configuration](#configuration), below. + +## App management + +It is possible for the throttler to respond differently -- to some extent -- to different clients, or _apps_. When a client asks for the throttler's advice, it may identify itself by any arbitrary name, which the throttler terms the _app_. For example, `vreplication` workflows identify by the name "vreplication", and Online DDL operations use "online-ddl", etc. + +It is possible to _restrict_ the throttler's response to one or more apps. For example, it's possible to completely throttle "vreplication" while still responding `HTTP 200` to other apps. This is typically used to give way or precedence to one or two apps, or otherwise to further reduce the incoming load from a specific app. + +Starting `v18`, it is also possible to _exempt_ an app from throttling, even if the throttler is otherwise rejecting requests with metrics beyond the threshold. This is an advanced feature that users should treat with great care, and only in situations where they absolutely must give a specific workflow/migration the highest priority above all else. See discussion in examples, below. + +## Configuration + +{{< warning >}} +Per-tablet throttler configuration, as used in `v15` and supported in `v16`, is no longer supported in `v18`.{{< /warning >}} + +Throttler configuration is found in the [local topology server](../../../concepts/topology-service/). There is one configuration per keyspace. All shards and all tablets in all cells have the same throttler configuration: they are all enabled or disabled, and all share the same threshold or custom query. Since configuration is stored outside the tablet, it survives tablet restarts. + +`v16` introduced a new opt-in `vttablet` flag, `--throttler-config-via-topo`, and the flag defaulted `false`. In `v17` the flag now defaulted to `true`. In `v18`, the flag is not used anymore, and the tablet looks for configuration in the topology server, and will watch and apply any changes made there. + +The following flags are deprecated (and will be removed in `v19`): + +- `--throttle_threshold` +- `--throttle_metrics_query` +- `--throttle_metrics_threshold` +- `--throttle_check_as_check_self` +- `--throttler-config-via-topo` + +The following flag was removed: + +- `--enable_lag_throttler` + +Updating the throttler config is done via `vtctlclient` or `vtctldclient`. For example: + +```sh +$ vtctlclient -- 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 +``` + +See [vtctl UpdateThrottlerConfig](../../programs/vtctl/throttler#updatethrottlerconfig). + +If you are still using the `v15` flags, you will have to transition to the new throttler configuration scheme: first populate topo with a new throttler configuration via `UpdateThrottlerConfig`. At the very least, set a `--threshold`. You likely also want to `--enable`. Then, reconfigure `vttablet`s with `--throttler-config-via-topo`, and restart them. + +The list of tablet types included in the throttler's logic is dictated by `vttablet --throttle_tablet_types`. The value is a comma delimited list of tablet types. The default value is `"replica"`. You may, for example, set it to be `"replica,rdonly"`. + +## Heartbeat configuration + +Enabling the lag throttler also automatically enables heartbeat injection. The follwing `vttablet` flags further control heartbeat behavior: + +- `--heartbeat_interval` indicates how frequently heartbeats are injected. The interval should over-sample the `--throttle_threshold`. For example, if `--throttle_threshold` is `1s`, then `--heartbeat_interval` should be `250ms` or less. +- `--heartbeat_on_demand_duration` ensures heartbeats are only injected when needed (e.g. during active VReplication workflows such as MoveTables or OnlineDDL). Heartbeats are written to the binary logs, and can therefore bloat them. If this is a concern, configure for example: `--heartbeat_on_demand_duration 5s`. This setting means: any throttler request starts a `5s` lease of heartbeat writes. + In normal times, heartbeats are not written. Once a throttle check is requested (e.g. by a running migration), the throttler asks the tablet to start a `5s` lease of heartbeats. that first check is likely to return a non-OK code, because heartbeats were stale. However, subsequent checks will soon pick up on the newly injected heartbeats. Checks made while the lease is held, further extend the lease time. In the scenario of a running migration, we can expect heartbeats to begin as soon as the migration begins, and terminate `5s` (in our example) after the migration completes. + A recommended value is a multiple of `--throttle_threshold`. If `--throttle_threshold` is `1s`, reasonable values would be `5s` to `60s`. + +## API & usage + +Applications use these API endpoints: + +### Checks + +- `/throttler/check?app=`, for apps that wish to write mass amounts of data to a shard, and wish to maintain the overall health of the shard. This check is only applicable on the `PRIMARY` tablet. +- `/throttler/check-self`, for apps that wish to perform some operation (e.g. a massive _read_) on a specific tablet and only wish to maintain the health of that tablet. This check is applicable on all tablets. + +#### Examples: + +- `gh-ost` uses this throttler endpoint: `/throttler/check?app=online-ddl:gh-ost:&p=low` +- A data backfill application will identify as such, and use _normal_ priority: `/throttler/check?app=my_backfill` (priority not indicated in URL therefore assumed to be _normal_) +- An app reading a massive amount of data directly from a replica tablet will use `/throttler/check-self?app=my_data_reader` + +A `HEAD` request is sufficient. A `GET` request also provides a `JSON` output. For example: + +- `{"StatusCode":200,"Value":0.207709,"Threshold":1,"Message":""}` +- `{"StatusCode":429,"Value":3.494452,"Threshold":1,"Message":"Threshold exceeded"}` +- `{"StatusCode":404,"Value":0,"Threshold":0,"Message":"No such metric"}` + +In the first two above examples we can see that the tablet is configured to throttle at `1sec` + +### Control + +All controls below apply to a given keyspace (`commerce` in the next examples). All of the keyspace's tablets, in all shards and cells, are affected. + +Enable the throttler: + +```sh +$ vtctldclient UpdateThrottlerConfig --enable commerce +``` + +Disable the throttler + +```sh +$ vtctldclient UpdateThrottlerConfig --disable commerce +``` + +Enable and also set a replication lag threshold: + +```sh +$ vtctldclient UpdateThrottlerConfig --enable --threshold 15.0 commerce +``` + +Set a custom query and a matching threshold. Does not affect enabled state: + +```sh +$ vtctldclient UpdateThrottlerConfig --custom-query "show global status like 'threads_running'" --threshold 40 --check-as-check-self commerce +``` + +In the above, we use `--check-as-check-self` because we want the shard's `PRIMARY`'s metric (concurrent threads) to be the throttling factor. + +Return to default throttling metric (replication lag): + +```sh +$ vtctldclient UpdateThrottlerConfig --custom-query "" --threshold 15.0 --check-as-check-shard commerce +``` + +In the above, we use `--check-as-check-self` because we want the shard's replicas metric (lag) to be the throttling factor. + +Throttle a specific app, `vreplication`, so that `80%` of its eligible requests are denied (slowing it down to `20%` potential speed), auto-expiring after `30` minutes: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-ratio=0.8 --throttle-app-duration "30m" commerce +``` + +Unthrottle an app: + +```sh +$ vtctldclient UpdateThrottlerConfig --unthrottle-app "vreplication" commerce +``` + +An altrnative method to unthrottle is to set a throttling rule that expires immediately: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-duration 0 commerce +``` + +Fully throttle all Online DDL (schema changes) for the next hour and a half: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "online-ddl" --throttle-app-ratio=1.0 --throttle-app-duration "1h30m" commerce +``` + +Exempt `vreplication` from being throttled, even if otherwise the metrics are past the throttler threshold (e.g. replication lag is high): + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-duration "30m" --throttle-app-exempt commerce +``` + +Use the above with great care. Exempting one app can cause starvation to all other apps. Consider, for example, the common use case where throttling is based on replication lag. By exempting `vreplication`, it is free to grab all the resources it wants. It is possible and likely that it will drive replication lag higher than the threshold, which means all other throttler clients will be fully throttled and with all requests rejected. + +Exemption times out just as other throttling rules. To remove an exemption, any of the following will do: + +```sh +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-exempt=false commerce +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-duration "0" commerce +$ vtctldclient UpdateThrottlerConfig --unthrottle-app "vreplication" commerce +``` + +### Information + +Throttler configuration is part of the `Keyspace` entry: + +```sh +$ vtctldclient GetKeyspace commerce +``` + +```json +{ + "name": "commerce", + "keyspace": { + "served_froms": [], + "keyspace_type": 0, + "base_keyspace": "", + "snapshot_time": null, + "durability_policy": "semi_sync", + "throttler_config": { + "enabled": true, + "threshold": 15.0, + "custom_query": "", + "check_as_check_self": false, + "throttled_apps": { + "vreplication": { + "name": "vreplication", + "ratio": 0.5, + "expires_at": { + "seconds": "1687864412", + "nanoseconds": 142717831 + } + } + } + }, + "sidecar_db_name": "_vt" + } +} +``` + +- `/throttler/status` endpoint. This is useful for monitoring and management purposes. + +Vitess also accepts the SQL syntax: + +- `SHOW VITESS_THROTTLER STATUS`: returns the status for all primary tables in the keyspace. See [MySQL Query Extensions](../mysql-query-extensions/#show-statements). + +#### Example: Healthy primary tablet + +The following command gets throttler status on a primary tablet hosted on `tablet1`, serving on port `15100`. + +```shell +$ curl -s 'http://tablet1:15100/throttler/status' | jq . +``` + +This API call returns the following JSON object: + +```json +{ + "Keyspace": "commerce", + "Shard": "80-c0", + "IsLeader": true, + "IsOpen": true, + "IsDormant": false, + "Query": "select unix_timestamp(now(6))-max(ts/1000000000) as replication_lag from _vt.heartbeat", + "Threshold": 1, + "AggregatedMetrics": { + "mysql/self": { + "Value": 0.749837 + }, + "mysql/shard": { + "Value": 0.749887 + } + }, + "MetricsHealth": { + "mysql/self": { + "LastHealthyAt": "2021-01-24T19:03:19.141933727+02:00", + "SecondsSinceLastHealthy": 0 + }, + "mysql/shard": { + "LastHealthyAt": "2021-01-24T19:03:19.141974429+02:00", + "SecondsSinceLastHealthy": 0 + } + } +} +``` + +The primary tablet serves two types of metrics: + +- `mysql/shard`: an aggregated lag on relevant replicas in this shard. This is the metric to check when writing massive amounts of data to this server. +- `mysql/self`: the health of the specific primary MySQL server backed by this tablet. + +`"IsLeader": true` indicates this tablet is active, is the `primary`, and is running probes. +`"IsDormant": false,` means that an application has recently issued a `check`, and the throttler is probing for lag at high frequency. + +#### Example: replica tablet + +The following command gets throttler status on a replica tablet hosted on `tablet2`, serving on port `15100`. + +```shell +$ curl -s 'http://tablet2:15100/throttler/status' | jq . +``` + +This API call returns the following JSON object: + +```json +{ + "Keyspace": "commerce", + "Shard": "80-c0", + "IsLeader": false, + "IsOpen": true, + "IsDormant": false, + "Query": "select unix_timestamp(now(6))-max(ts/1000000000) as replication_lag from _vt.heartbeat", + "Threshold": 1, + "AggregatedMetrics": { + "mysql/self": { + "Value": 0.346409 + } + }, + "MetricsHealth": { + "mysql/self": { + "LastHealthyAt": "2021-01-24T19:04:25.038290475+02:00", + "SecondsSinceLastHealthy": 0 + } + } +} +``` + +The replica tablet only presents `mysql/self` metric (measurement of its own backend MySQL's lag). It does not serve checks for the shard in general. + + +## Resources + +- [freno](https://github.com/github/freno) project page +- [Mitigating replication lag and reducing read load with freno](https://github.blog/2017-10-13-mitigating-replication-lag-and-reducing-read-load-with-freno/), a GitHub Engineering blog post diff --git a/content/en/docs/19.0/reference/features/topology-service.md b/content/en/docs/19.0/reference/features/topology-service.md new file mode 100644 index 000000000..8ec6e1f8a --- /dev/null +++ b/content/en/docs/19.0/reference/features/topology-service.md @@ -0,0 +1,746 @@ +--- +title: Topology Service +weight: 20 +aliases: ['/docs/user-guides/topology-service/','/docs/reference/topology-service/'] +--- + +This document describes the Topology Service, a key part of the Vitess architecture. This service is exposed to all Vitess processes, and is used to store small pieces of configuration data about the Vitess cluster, and provide cluster-wide locks. It also supports watches, and primary election. + +Vitess uses a plugin implementation to support multiple backend technologies for the Topology Service (etcd, ZooKeeper, Consul). Concretely, the Topology Service handles two functions: it is both a [distributed lock manager](http://en.wikipedia.org/wiki/Distributed_lock_manager) and a repository for topology metadata. In earlier versions of Vitess, the Topology Serice was also referred to as the Lock Service. + +## Requirements and usage + +The Topology Service is used to store information about the Keyspaces, the +Shards, the Tablets, the Replication Graph, and the Serving Graph. We store +small data structures (a few hundred bytes) per object. + +The main contract for the Topology Service is to be very highly available and +consistent. It is understood it will come at a higher latency cost and very low +throughput. + +We never use the Topology Service as an RPC or queuing mechanism or as a storage +system for logs. We never depend on the Topology Service being responsive and +fast to serve every query. + +The Topology Service must also support a Watch interface, to signal when certain +conditions occur on a node. This is used, for instance, to know when the Keyspace +topology changes (e.g. for resharding). + +### Global vs Local + +We differentiate two instances of the Topology Service: the Global instance, and +the per-cell Local instance: + +* The Global instance is used to store global data about the topology that + doesn’t change very often, e.g. information about Keyspaces and Shards. + The data is independent of individual instances and cells, and needs + to survive a cell going down entirely. +* There is one Local instance per cell, that contains cell-specific information, + and also rolled-up data from the Global + Local cell to make it easier for + clients to find the data. The Vitess local processes should not use the Global + topology instance, but instead the rolled-up data in the Local topology + server as much as possible. + +The Global instance can go down for a while and not impact the local cells (an +exception to that is if a reparent needs to be processed, it might not work). If +a Local instance goes down, it only affects the local tablets in that instance +(and then the cell is usually in bad shape, and should not be used). + +Vitess will not use the global or local topology service as part of serving individual queries. The Topology Service is only used to get the topology information at startup and in the background. + +### Recovery + +If a Local Topology Service dies and is not recoverable, it can be wiped out. All +the tablets in that cell then need to be restarted so they re-initialize their +topology records (but they won’t lose any MySQL data). + +If the Global Topology Service dies and is not recoverable, this is more of a +problem. All the Keyspace / Shard objects have to be recreated or be restored. +Then the cells should recover. + +## Global data + +This section describes the data structures stored in the Global instance of the +topology service. + +### Keyspace + +The Keyspace object contains various information, mostly about sharding: how is +this Keyspace sharded, what is the name of the sharding key column, is this +Keyspace serving data yet, how to split incoming queries, … + +An entire Keyspace can be locked. We use this during resharding for instance, +when we change which Shard is serving what inside a Keyspace. That way we +guarantee only one operation changes the Keyspace data concurrently. + +### Shard + +A Shard contains a subset of the data for a Keyspace. The Shard record in the +Global topology service contains: + +* the primary tablet alias for this shard (that has the MySQL primary). +* the sharding key range covered by this Shard inside the Keyspace. +* the tablet types this Shard is serving (primary, replica, batch, …), per cell + if necessary. +* if using filtered replication, the source shards this shard is replicating + from. +* the list of cells that have tablets in this shard. +* shard-global tablet controls, like denied tables no tablet should serve + in this shard. + +A Shard can be locked. We use this during operations that affect either the +Shard record, or multiple tablets within a Shard (like reparenting), so multiple +tasks cannot concurrently alter the data. + +### VSchema data + +The VSchema data contains sharding and routing information for +the [VTGate API](https://github.com/vitessio/vitess/blob/main/doc/design-docs/VTGateV3Features.md). + +## Local data + +This section describes the data structures stored in the Local instance (per +cell) of the topology service. + +### Tablets + +The Tablet record has a lot of information about each vttablet process +making up each tablet (along with the MySQL process): + +* the Tablet Alias (cell+unique id) that uniquely identifies the Tablet. +* the Hostname, IP address and port map of the Tablet. +* the current Tablet type (primary, replica, batch, spare, …). +* which Keyspace / Shard the tablet is part of. +* the sharding Key Range served by this Tablet. +* user-specified tag map (e.g. to store per-installation data). + +A Tablet record is created before a tablet can be running (by passing the `init_*` parameters to the vttablet process). +The only way a Tablet record will be updated is one of: + +* The vttablet process itself owns the record while it is running, and can + change it. +* At init time, before the tablet starts. +* After shutdown, when the tablet gets deleted. +* If a tablet becomes unresponsive, it may be forced to spare to make it + unhealthy when it restarts. + +### Replication graph + +The Replication Graph allows us to find Tablets in a given Cell / Keyspace / +Shard. It used to contain information about which Tablet is replicating from +which other Tablet, but that was too complicated to maintain. Now it is just a +list of Tablets. + +### Serving graph + +The Serving Graph is what the clients use to find the per-cell topology of a +Keyspace. It is a roll-up of global data (Keyspace + Shard). vtgates only open a +small number of these objects and get all the information they need quickly. + +#### SrvKeyspace + +It is the local representation of a Keyspace. It contains information on what +shard to use for getting to the data (but not information about each individual +shard): + +* the partitions map is keyed by the tablet type (primary, replica, batch, …) and + the value is a list of shards to use for serving. +* it also contains the global Keyspace fields, copied for fast access. + +It can be rebuilt by running `vtctl RebuildKeyspaceGraph `. It is +automatically rebuilt when a tablet starts up in a cell and the SrvKeyspace +for that cell / keyspace does not exist yet. It will also be changed +during horizontal and vertical splits. + +#### SrvVSchema + +It is the local roll-up for the VSchema. It contains the VSchema for all +keyspaces in a single object. + +It can be rebuilt by running `vtctl RebuildVSchemaGraph`. It is automatically +rebuilt when using `vtctl ApplyVSchema` (unless prevented by flags). + +## Workflows involving the Topology Service + +The Topology Service is involved in many Vitess workflows. + +When a Tablet is initialized, we create the Tablet record, and add the Tablet to +the Replication Graph. If it is the primary for a Shard, we update the global +Shard record as well. + +Administration tools need to find the tablets for a given Keyspace / Shard. To retrieve this: + +* first we get the list of Cells that have Tablets for the Shard (global topology +Shard record has these) +* then we use the Replication Graph for that Cell / +Keyspace / Shard to find all the tablets then we can read each tablet record. + +When a Shard is reparented, we need to update the global Shard record with the +new primary alias. + +Finding a tablet to serve the data is done in two stages: + +* vtgate maintains a health check connection to all possible tablets, and they +report which Keyspace / Shard / Tablet type they serve. +* vtgate also reads the SrvKeyspace object, to find out the shard map. + +With these two pieces of information, vtgate can route the query to the right vttablet. + +During resharding events, we also change the topology significantly. A horizontal split +will change the global Shard records, and the local SrvKeyspace records. A +vertical split will change the global Keyspace records, and the local +SrvKeyspace records. + +## Exploring the data in a Topology Service + +We store the proto3 serialized binary data for each object. + +We use the following paths for the data, in all implementations: + +*Global Cell*: + +* CellInfo path: `cells//CellInfo` +* Keyspace: `keyspaces//Keyspace` +* Shard: `keyspaces//shards//Shard` +* VSchema: `keyspaces//VSchema` + +*Local Cell*: + +* Tablet: `tablets/-/Tablet` +* Replication Graph: `keyspaces//shards//ShardReplication` +* SrvKeyspace: `keyspaces//SrvKeyspace` +* SrvVSchema: `SvrVSchema` + +The `vtctl TopoCat` utility can decode these files when using the +`--decode_proto` option: + +``` sh +GLOBAL_TOPOLOGY="--topo_implementation zk2 --topo_global_server_address global_server1,global_server2 --topo_global_root /vitess/global" + +$ vtctl ${GLOBAL_TOPOLOGY} TopoCat -- --decode_proto --long /keyspaces/*/Keyspace +path=/keyspaces/ks1/Keyspace version=53 +sharding_column_name: "col1" +path=/keyspaces/ks2/Keyspace version=55 +sharding_column_name: "col2" +``` + +The VTAdmin web tool also contains a topology browser (use the `Topology` +tab on the left side). It will display the various proto files, decoded. + +## Implementations + +The Topology Service interfaces are defined in our code in `go/vt/topo/`, +specific implementations are in `go/vt/topo/`, and we also have +a set of unit tests for it in `go/vt/topo/test`. + +This part describes the implementations we have, and their specific +behavior. + +If starting from scratch, please use the `zk2`, `etcd2` or `consul` +implementations. We deprecated the old `zookeeper` and `etcd` +implementations. See the migration section below if you want to migrate. + +### Zookeeper `zk2` implementation + +This is the current implementation when using Zookeeper. (The old `zookeeper` +implementation is deprecated). + +The global cell typically has around 5 servers, distributed one in each +cell. The local cells typically have 3 or 5 servers, in different server racks / +sub-networks for higher resilience. For our integration tests, we use a single +ZK server that serves both global and local cells. + +We provide the `zk` utility for easy access to the topology data in +Zookeeper. It can list, read and write files inside any Zoopeeker server. Just +specify the `-server` parameter to point to the Zookeeper servers. Note the +VTAdmin UI can also be used to see the contents of the topology data. + +To configure a Zookeeper installation, let's start with the global cell +service. It is described by the addresses of the servers (comma separated list), +and by the root directory to put the Vitess data in. For instance, assuming we +want to use servers `global_server1,global_server2` in path `/vitess/global`: + +``` sh +# The root directory in the global server will be created +# automatically, same as when running this command: +# zk -server global_server1,global_server2 touch -p /vitess/global + +# Set the following flags to let Vitess use this global server: +# --topo_implementation zk2 +# --topo_global_server_address global_server1,global_server2 +# --topo_global_root /vitess/global +``` + +Then to add a cell whose local topology service `cell1_server1,cell1_server2` +will store their data under the directory `/vitess/cell1`: + +``` sh +GLOBAL_TOPOLOGY="--topo_implementation zk2 --topo_global_server_address global_server1,global_server2 --topo_global_root /vitess/global" + +# Reference cell1 in the global topology service: +vtctl ${GLOBAL_TOPOLOGY} AddCellInfo -- \ + --server_address cell1_server1,cell1_server2 \ + --root /vitess/cell1 \ + cell1 +``` + +If only one cell is used, the same Zookeeper instance can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address, and very importantly a *different* root directory. + +[Zookeeper Observers](https://zookeeper.apache.org/doc/current/zookeeperObservers.html) can +also be used to limit the load on the global Zookeeper. They are configured by +specifying the addresses of the observers in the server address, after a `|`, +for instance: +`global_server1:p1,global_server2:p2|observer1:po1,observer2:po2`. + +#### Implementation details + +We use the following paths for Zookeeper specific data, in addition to the +regular files: + +* Locks sub-directory: `locks/` (for instance: + `keyspaces//Keyspace/locks/` for a keyspace) +* Leader election path: `elections/` + +Both locks and primary election are implemented using ephemeral, sequential files +which are stored in their respective directory. + +### etcd `etcd2` implementation (new version of `etcd`) + +This topology service plugin is meant to use etcd clusters as storage backend +for the topology data. This topology service supports version 3 and up of the +etcd server. + +This implementation is named `etcd2` because it supersedes our previous +implementation `etcd`. Note that the storage format has been changed with the +`etcd2` implementation, i.e. existing data created by the previous `etcd` +implementation must be migrated manually (See migration section below). + +To configure an `etcd2` installation, let's start with the global cell +service. It is described by the addresses of the servers (comma separated list), +and by the root directory to put the Vitess data in. For instance, assuming we +want to use servers `http://global_server1,http://global_server2` in path +`/vitess/global`: + +``` sh +# Set the following flags to let Vitess use this global server, +# and simplify the example below: +# --topo_implementation etcd2 +# --topo_global_server_address http://global_server1,http://global_server2 +# --topo_global_root /vitess/global +GLOBAL_TOPOLOGY="--topo_implementation etcd2 --topo_global_server_address http://global_server1,http://global_server2 --topo_global_root /vitess/global" +``` + +Then to add a cell whose local topology service +`http://cell1_server1,http://cell1_server2` will store their data under the +directory `/vitess/cell1`: + +``` sh +# Reference cell1 in the global topology service: +# (the TOPOLOGY variable is defined in the previous section) +vtctl ${GLOBAL_TOPOLOGY} AddCellInfo -- \ + --server_address http://cell1_server1,http://cell1_server2 \ + --root /vitess/cell1 \ + cell1 +``` + +If only one cell is used, the same etcd instances can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address and, very importantly, a *different* root directory. + +#### Implementation details + +For locks, we use a subdirectory named `locks` in the directory to lock, and an +ephemeral file in that subdirectory (it is associated with a lease, whose TTL +can be set with the `--topo_etcd_lease_duration` flag, defaults to 30 +seconds). The ephemeral file with the lowest ModRevision has the lock, the +others wait for files with older ModRevisions to disappear. + +Leader elections also use a subdirectory, named after the election Name, and use +a similar method as the locks, with ephemeral files. + +We store the proto3 binary data for each object (as the API allows us to store +binary data). Note that this means that if you want to interact with etcd using +the `etcdctl` tool, you will have to tell it to use the v3 API, e.g.: + +``` +ETCDCTL_API=3 etcdctl get / --prefix --keys-only +``` + +### Consul `consul` implementation + +This topology service plugin is meant to use Consul clusters as storage backend +for the topology data. + +To configure a `consul` installation, let's start with the global cell +service. It is described by the address of a server, +and by the root node path to put the Vitess data in (it cannot start with `/`). For instance, assuming we +want to use servers `global_server:global_port` with node path +`vitess/global`: + +``` sh +# Set the following flags to let Vitess use this global server, +# and simplify the example below: +# --topo_implementation consul +# --topo_global_server_address global_server:global_port +# --topo_global_root vitess/global +GLOBAL_TOPOLOGY="--topo_implementation consul --topo_global_server_address global_server:global_port --topo_global_root vitess/global" +``` + +Then to add a cell whose local topology service +`cell1_server1:cell1_port` will store their data under the +directory `vitess/cell1`: + +``` sh +# Reference cell1 in the global topology service: +# (the TOPOLOGY variable is defined in the previous section) +vtctl ${GLOBAL_TOPOLOGY} AddCellInfo -- \ + --server_address cell1_server1:cell1_port \ + --root vitess/cell1 \ + cell1 +``` + +If only one cell is used, the same consul instances can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address and, very importantly, a *different* root node path. + +#### Implementation details + +For locks, we use a file named `Lock` in the directory to lock, and the regular +Consul Lock API. + +Leader elections use a single lock file (the Election path) and the regular +Consul Lock API. The contents of the lock file is the ID of the current primary. + +Watches use the Consul long polling Get call. They cannot be interrupted, so we +use a long poll whose duration is set by the +`-topo_consul_watch_poll_duration` flag. Canceling a watch may have to +wait until the end of a polling cycle with that duration before returning. + +## Running multi cell environments + +When running an environment with multiple cells, it is essential to first create +and configure your global topology service. Then define each local topology +service to the global topology. As mentioned previously, the global +and local topology service can reside on the same or separate implementation of +etcd, zookeeper, or consul. At a higher level overview: + +* Create or locate an existing instance of etcd, zookeeper, or consul for the + global topology service. +* Use vtctl client commands to initialize the global topology service, + providing the global topology implementation, and root directory. + NOTE: for best practices the root dir should be set to `/vitess/global` (on + consul this should be `vitess/global`). +* (Optional) For each cell create an instance of etcd, zookeeper, or consul for + the local topology service. This step is optional as you may use the existing + implementation used by the global topology service. If you create a new local + instances, the technologies must match. For example, if you are using etcd for + your global topology service then you must use etcd for your local topology + service. +* For each cell, using the vtctl client commands, define the local topology + service with the global topology service. This is done by providing the global + topology service with the cell name, the local topology service, and the root + directory. NOTE: for best practices the local root dir should be set to + `/vitess/${CELL_NAME}` (on consul this should be `vitess/${CELL_NAME}`) where `${CELL_NAME}` is the location of the cell + `us-east-1, eu-west-2, etc`. +* When starting a vttablet instance you must provide the global topology service + as well as the `-tablet-path`, which implicitly includes the cell details. + With this information the vttablet process will read the local topology + details from the global topology server. +* When starting a vtgate instance, you will provide the global topology + service, as well as the `-cell` flag to explicitly provide the cell details. + With this information the vtgate process will retrieve the connection details + it needs to connect to the applicable local topology server(s). Unlike the + vttablet process, if you are watching more than one cell, in `--cells_to_watch` + you may connect to multiple local topology services. + + +### Simple local configuration + +For this example run through, we will be using two etcd services one for +the global and one for local topology service. + +{{< warning >}} +Production environments can and should be configured with multiple +topology instances at the global and local levels. +{{< /warning >}} + + +1. Create the global etcd service + +``` sh +export VTDATAROOT="/vt" +TOKEN="SOMETHING_UNIQ_HERE" +GLOBAL_ETCD_IP="192.168.0.2" +GLOBAL_ETCD_SERVER="http://${GLOBAL_ETCD_IP}:2379" +GLOBAL_ETCD_PEER_SERVER="http://${GLOBAL_ETCD_IP}:2380" + +etcd --enable-v2=true --data-dir ${VTDATAROOT}/etcd/global --listen-client-urls ${GLOBAL_ETCD_SERVER} \ + --name=global --advertise-client-urls ${GLOBAL_ETCD_SERVER} --listen-peer-urls ${GLOBAL_ETCD_PEER_SERVER} \ + --initial-advertise-peer-urls ${GLOBAL_ETCD_PEER_SERVER} --initial-cluster global=${GLOBAL_ETCD_PEER_SERVER} \ + --initial-cluster-token=${TOKEN} --initial-cluster-state=new \ + ${OTHER_ETCD_FLAGS} +``` + +2. Configure vtctld to use the global topology service + +``` sh +vtctld --topo_implementation=etcd2 --topo_global_server_address=${GLOBAL_ETCD_SERVER} \ + --topo_global_root=/vitess/global --port=15000 --grpc_port=15999 --service_map='grpc-vtctl,grpc-vtctld' \ + ${OTHER_VTCTLD_FLAGS} +``` + +3. Create a local etcd instance to store our cell information + +``` sh +CELL_NAME="US_EAST" +CELL_TOKEN="${CELL_NAME}" +CELL_ETCD_IP="192.168.0.3" +CELL_ETCD_SERVER="http://${CELL_ETCD_IP}:2379" +CELL_ETCD_PEER_SERVER="http://${CELL_ETCD_IP}:2380" + +etcd --enable-v2=true --data-dir ${VTDATAROOT}/etcd/${CELL_NAME} --listen-client-urls ${CELL_ETCD_SERVER} \ + --name=${CELL_NAME} --advertise-client-urls ${CELL_ETCD_SERVER} --listen-peer-urls ${CELL_ETCD_PEER_SERVER} \ + --initial-advertise-peer-urls ${CELL_ETCD_PEER_SERVER} --initial-cluster ${CELL_NAME}=${CELL_ETCD_PEER_SERVER} \ + --initial-cluster-token=${CELL_TOKEN} --initial-cluster-state=new \ + ${OTHER_ETCD_FLAGS} +``` + +4. Define the local topology service in the global topology service using vtctl +client commands. We are providing the global topolgy server three pieces of +information about the local topology service: + * `--root=` the root of our local topology server + * `--server_address` comma separated connection details to our local etcd + instance(s). In this example, it is only a single instance + * `${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 +# The daemon already has the global topology information, therefore, we do not +# need to explicitly provide these details. + +vtctlclient --server ${VTCTLD_IP}:15999 AddCellInfo -- \ + --root=/vitess/${CELL_NAME} \ + --server_address=${CELL_ETCD_SERVER} \ + ${CELL_NAME} +``` + +5. When starting up a new vttablet instances, you will need to provide +the global topology details, as well as the alias of the tablet, provided through +`--tablet-path=${TABLET_ALIAS}`. With the alias vttablet will acquire the cell +name and retrieve the local topology information from the global topology server. +NOTE: the `${TABLET_ALIAS}` variable is composed of two parts, the `${CELL_NAME}` +and the `${TABLET_UID}`. The `${TABLET_ALIAS}` must be unique within the cluster +and the `${TABLET_UID}` must be unique numerical value within the cell. + +```sh +# vttablet implementation +GLOBAL_TOPOLOGY="--topo_implementation etcd2 --topo_global_server_address ${GLOBAL_ETCD_SERVER} --topo_global_root /vitess/global" +TABLET_UID="100" +CELL_NAME="US_EAST" +TABLET_ALIAS="${CELL_NAME}-${TABLET_UID}" +KEYSPACE="CustomerInfo" + +vttablet ${GLBOAL_TOPOLOGY} --tablet-path=${TABLET_ALIAS} --tablet_dir=${VTDATAROOT}/${TABLET_ALIAS} \ + --mycnf-file=${VTDATAROOT}/${TABLET_ALIAS}/my.cnf --init_keyspace=${KEYSPACE} \ + --init_shard=0 --init_tablet_type=replica --port=15100 --grpc_port=16100 \ + --service_map='grpc-queryservice,grpc-tabletmanager,grpc-updatestream' \ + ${OTHER_VTTABLET_FLAGS} +``` + +5. When starting up a new vtgate instances, you will explicitly provide cell +details with `--cell` flag, and the global topology details. vtgate may be aware +of additional local topology services if `--cells_to_watch` contains more than +one cell. Local Topology information will be retrieved from the global toplogy +server for each cell vtgate is aware of. + +```sh +# vtgate implementation +GLOBAL_TOPOLOGY="--topo_implementation etcd2 --topo_global_server_address ${GLOBAL_ETCD_SERVER} --topo_global_root /vitess/global" +CELL_NAME="US_EAST" + +vtgate ${GLOBAL_TOPOLOGY} --cell=${CELL_NAME} --cells_to_watch=${CELL_NAME} --port=15001 --grpc_port=15991 \ +--mysql_server_port=25306 --mysql_auth_server_impl=none --service_map='grpc-vtgateservice' \ +--tablet_types_to_wait PRIMARY,REPLICA \ +${OTHER_VTGATE_FLAGS} +``` + +6. You can repeat steps 3 through 5 above to create each cell as needed. If you +have a vtgate instance that is watching a new and old cell with `-cells_to_watch`, +you may have to rebuild the topology for the Keyspace and VSchema. This will +propagate information from the global topology service back to the local topology +services + +```sh +vtctlclient --server ${VTCTLD_IP}:15999 RebuildKeyspaceGraph ${KEYSPACE_NAME} +vtctlclient --server ${VTCTLD_IP}:15999 RebuildVSchemaGraph +``` + + +## Running single cell environments + +The topology service is meant to be distributed across multiple cells, and +survive single cell outages. However, one common usage is to run a Vitess +cluster in only one cell / region. This part explains how to do this, and later +on upgrade to multiple cells / regions. + +If running in a single cell, the same topology service can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address and, very importantly, a *different* root node path. + +In that case, just running 3 servers for topology service quorum is probably +sufficient. For instance, 3 etcd servers. And use their address for the local +cell as well. Let's use a short cell name, like `local`, as the local data in +that topology service will later on be moved to a different topology service, +which will have the real cell name. + +### Extending to more cells + +To then run in multiple cells, the current topology service needs to be split +into a global instance and one local instance per cell. Whereas, the initial +setup had 3 topology servers (used for global and local data), we recommend to +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 +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 +the `--cells_to_watch` command line parameter. It can then use all tablets in +all cells to route traffic. Note this is necessary to access the primary in +another cell. + +After the extension to two cells, the original topo service contains both the +global topology data, and the first cell topology data. The more symmetrical +configuration we are after would be to split that original service into two: a +global one that only contains the global data (spread across both cells), and a +local one to the original cells. To achieve that split: + +* Start up a new local topology service in that original cell (3 more local + servers in that cell). +* Pick a name for that cell, different from `local`. +* Use `vtctl AddCellInfo` to configure it. +* Make sure all vtgates can see that new local cell (again, using + `--cells_to_watch`). +* Restart all vttablets to be in that new cell, instead of the `local` cell name + used before. +* Use `vtctl RemoveKeyspaceCell` to remove all mentions of the `local` cell in + all keyspaces. +* Use `vtctl RemoveCellInfo` to remove the global configurations for that + `local` cell. +* Remove all remaining data in the global topology service that are in the old + local server root. + +After this split, the configuration is completely symmetrical: + +* a global topology service, with servers in all cells. Only contains global + topology data about Keyspaces, Shards and VSchema. Typically it has 5 servers + across all cells. +* a local topology service to each cell, with servers only in that cell. Only + contains local topology data about Tablets, and roll-ups of global data for + efficient access. Typically, it has 3 servers in each cell. + +## Migration between implementations + +We provide the `topo2topo` utility to migrate between one implementation +and another of the topology service. + +The process to follow in that case is: + +* Start from a stable topology, where no resharding or reparenting is ongoing. +* Configure the new topology service so it has at least all the cells of the + source topology service. Make sure it is running. +* Run the `topo2topo` program with the right flags. `--from_implementation`, + `--from_root`, `--from_server` describe the source (old) topology + service. `--to_implementation`, `--to_root`, `--to_server` describe the + destination (new) topology service. +* Run `vtctl RebuildKeyspaceGraph` for each keyspace using the new topology + service flags. +* Run `vtctl RebuildVSchemaGraph` using the new topology service flags. +* Restart all `vtgate` processes using the new topology service flags. They + will see the same Keyspaces / Shards / Tablets / VSchema as before, as the + topology was copied over. +* Restart all `vttablet` processes using the new topology service flags. + They may use the same ports or not, but they will update the new topology + when they start up, and be visible from `vtgate`. +* Restart all `vtctld` processes using the new topology service flags. So that + the UI also shows the new data. + +Sample commands to migrate from deprecated `zookeeper` to `zk2` +topology would be: + +``` sh +# Let's assume the zookeeper client config file is already +# exported in $ZK_CLIENT_CONFIG, and it contains a global record +# pointing to: global_server1,global_server2 +# an a local cell cell1 pointing to cell1_server1,cell1_server2 +# +# The existing directories created by Vitess are: +# /zk/global/vt/... +# /zk/cell1/vt/... +# +# The new zk2 implementation can use any root, so we will use: +# /vitess/global in the global topology service, and: +# /vitess/cell1 in the local topology service. + +# Create the new topology service roots in global and local cell. +zk -server global_server1,global_server2 touch -p /vitess/global +zk -server cell1_server1,cell1_server2 touch -p /vitess/cell1 + +# Store the flags in a shell variable to simplify the example below. +GLOBAL_TOPOLOGY="--topo_implementation zk2 --topo_global_server_address global_server1,global_server2 --topo_global_root /vitess/global" + +# Reference cell1 in the global topology service: +vtctl ${GLOBAL_TOPOLOGY} AddCellInfo -- \ + --server_address cell1_server1,cell1_server2 \ + --root /vitess/cell1 \ + cell1 + +# Now copy the topology. Note the old zookeeper implementation does not need +# any server or root parameter, as it reads ZK_CLIENT_CONFIG. +topo2topo \ + --from_implementation zookeeper \ + --to_implementation zk2 \ + --to_server global_server1,global_server2 \ + --to_root /vitess/global \ + +# Rebuild SvrKeyspace objects in new service, for each keyspace. +vtctl ${GLOBAL_TOPOLOGY} RebuildKeyspaceGraph keyspace1 +vtctl ${GLOBAL_TOPOLOGY} RebuildKeyspaceGraph keyspace2 + +# Rebuild SrvVSchema objects in new service. +vtctl ${GLOBAL_TOPOLOGY} RebuildVSchemaGraph + +# Now restart all vtgate, vttablet, vtctld processes replacing: +# --topo_implementation zookeeper +# With: +# --topo_implementation zk2 +# --topo_global_server_address global_server1,global_server2 +# --topo_global_root /vitess/global +# +# After this, the ZK_CLIENT_CONF file and environment variables are not needed +# any more. +``` + +### Migration using the `Tee` implementation + +If your migration is more complex, or has special requirements, we also support +a 'tee' implementation of the topo service interface. It is defined in +`go/vt/topo/helpers/tee.go`. It allows communicating to two topo services, +and the migration uses multiple phases: + +* Start with the old topo service implementation we want to replace. +* Bring up the new topo service, with the same cells. +* Use `topo2topo` to copy the current data from the old to the new topo. +* Configure a `Tee` topo implementation to maintain both services. + * Note we do not expose a plugin for this, so a small code change is necessary. + * all updates will go to both services. + * the `primary` topo service is the one we will get errors from, if any. + * the `secondary` topo service is just kept in sync. + * at first, use the old topo service as `primary`, and the new one as + `secondary`. + * then, change the configuration to use the new one as `primary`, and the + old one as `secondary`. Reverse the lock order here. + * then rollout a configuration to just use the new service. diff --git a/content/en/docs/19.0/reference/features/transport-security-model.md b/content/en/docs/19.0/reference/features/transport-security-model.md new file mode 100644 index 000000000..12fddd2eb --- /dev/null +++ b/content/en/docs/19.0/reference/features/transport-security-model.md @@ -0,0 +1,125 @@ +--- +title: Transport Security Model +weight: 12 +aliases: ['/docs/user-guides/transport-security-model/','/docs/reference/transport-security-model/'] +--- + +Vitess exposes a few RPC services and internally uses RPCs. These RPCs can optionally utilize secure transport options to use TLS over the gRPC HTTP/2 transport protocol. This document explains how to use these features. Finally, we briefly cover how to secure the MySQL protocol transport to VTGate. + +## Overview + +The following diagram represents all the RPCs we use in a Vitess cluster via gRPC: + +![Vitess Transport Security Model Diagram](../../img/vitesstransportsecuritymodel.png) + +There are two main categories: + +* Internal RPCs: They are used to connect Vitess components. +* Externally visible RPCs: They are used by the app to talk to Vitess. Note that it is not necessary to use this gRPC interface. It is still possible to instead use the MySQL protocol to VTGate, which is not covered in this document. + +A few features in the Vitess ecosystem depend on authentication including Caller ID and table ACLs. + +## Caller ID + +Caller ID is a feature provided by the Vitess stack to identify the source of queries. There are two different Caller IDs: + +* Immediate Caller ID: It represents the secure client identity when it enters the Vitess side: + - It is a single string representing the user connecting to Vitess (VTGate). + - It is authenticated by the transport layer used. + - It can be used by the Vitess TableACL feature. +* Effective Caller ID: It provides detailed information on the individual caller process: + - It contains more information about the caller: principal, component, and sub-component. + - It is provided by the application layer. + - It is not authenticated. + - It is exposed in query logs. Enabling it can be useful for debugging issues like the source of a slow query. + +## gRPC Transport + +### gRPC Encrypted Transport + +When using gRPC transport, Vitess can use the usual TLS security features. Please note that familiarity with TLS is necessary here: + +* Any Vitess server can be configured to use TLS with the following command line parameters: + - `--grpc_cert`, `--grpc_key`: server cert and key to use. + - `--grpc_ca` (optional): client cert chains to trust. If specified, the client must then use a certificate signed by one of the CA certs in the provided file. +* A Vitess go client can be configured with symmetrical parameters to enable + TLS: + - `--[vtgate|tablet]_grpc_ca`: list of server cert signers to trust. I.E. the client will only connect to servers presenting a cert signed by one of the CAs in this file. + - `--[vtgate|tablet]_grpc_server_name`: common name of the server cert to trust. Instead of the hostname used to connect or IP SAN if using an IP to connect. + - `--[vtgate|tablet]_grpc_cert`, `--[vtgate|tablet]_grpc_key`: client side cert and key to use in cases when the server requires client authentication. + * Other clients can take similar parameters, in various ways. Please view each client's parameters for more information. + +With these options, it is possible to use TLS-secured connections for all parts of the gRPC system. This enables the server side to authenticate the client, and/or the client to authenticate the server. + +This is not enabled by default, as usually the different Vitess servers will run on a private network. It is also important to note, that in a Cloud environment, for example, usually all local traffic is already secured between VMs. + +### Options for vtctld + + | Name | Type | Definition | +| :-------- | :--------- | :--------- | +| --tablet_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_grpc_cert | string | the cert to use to connect | +| --tablet_grpc_key | string | the key to use to connect | +| --tablet_grpc_server_name | string | the server name to use to validate server certificate | +| --tablet_manager_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_manager_grpc_cert | string | the cert to use to connect | +| --tablet_manager_grpc_key | string | the key to use to connect | +| --tablet_manager_grpc_server_name | string | the server name to use to validate server certificate | +| --throttler_client_grpc_ca | string | the server ca to use to validate servers when connecting | +| --throttler_client_grpc_cert | string | the cert to use to connect | +| --throttler_client_grpc_key | string | the key to use to connect | +| --throttler_client_grpc_server_name | string | the server name to use to validate server certificate | +| --vtgate_grpc_ca | string | the server ca to use to validate servers when connecting | +| --vtgate_grpc_cert | string | the cert to use to connect | +| --vtgate_grpc_key | string | the key to use to connect | +| --vtgate_grpc_server_name | string | the server name to use to validate server certificate | + +### Options for vtgate + + | Name | Type | Definition | +| :-------- | :--------- | :--------- | +| --tablet_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_grpc_cert | string | the cert to use to connect | +| --tablet_grpc_key | string | the key to use to connect | +| --tablet_grpc_server_name | string | the server name to use to validate server certificate | + +### Options for vttablet + + | Name | Type | Definition | +| :-------- | :--------- | :--------- | +| --binlog_player_grpc_ca | string | the server ca to use to validate servers when connecting | +| --binlog_player_grpc_cert | string | the cert to use to connect | +| --binlog_player_grpc_key | string | the key to use to connect | +| --binlog_player_grpc_server_name | string | the server name to use to validate server certificate | +| --tablet_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_grpc_cert | string | the cert to use to connect | +| --tablet_grpc_key | string | the key to use to connect | +| --tablet_grpc_server_name | string | the server name to use to validate server certificate | +| --tablet_manager_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_manager_grpc_cert | string | the cert to use to connect | +| --tablet_manager_grpc_key | string | the key to use to connect | +| --tablet_manager_grpc_server_name | string | the server name to use to validate server certificate | + +### Certificates and Caller ID + +Additionally, if a client uses a certificate to connect to Vitess (VTGate) via gRPC, the common name of that certificate is passed to vttablet as the Immediate Caller ID. It can then be used by table ACLs to grant read, write or admin access to individual tables. This should be used if different clients should have different access to Vitess tables. + +### Caller ID Override + +In a private network, where TLS security is not required, it might still be desirable to use table ACLs as a safety mechanism to prevent a user from accessing sensitive data. The gRPC connector provides the `grpc_use_effective_callerid` flag for this purpose: if specified when running vtgate, the Effective Caller ID's principal is copied into the Immediate Caller ID, and then used throughout the Vitess stack. + +**Important**: This is not secure. Any user code can provide any value for the Effective Caller ID's principal, and therefore access any data. This is intended as a safety feature to make sure some applications do not misbehave. Therefore, this flag is not enabled by default. + +Another way to customize the immediateCallerID is to set the `grpc-use-static-authentication-callerid` flag on vtgate, which is only effective if you're using the static authentication plugin with vtgate. In this case, the username from the current authenticated session to vtgate is copied over as the Immediate Caller ID, and used throughout the Vitess stack. + +### Example + +For a concrete example, see [encrypted_transport_test.go](https://github.com/vitessio/vitess/blob/main/go/test/endtoend/encryption/encryptedtransport/encrypted_transport_test.go) in the source tree. + +It first sets up all the certificates, some table ACLs, and then uses the golang client to connect with TLS. It also exercises the `grpc_use_effective_callerid` flag, by connecting without TLS. + +## MySQL Transport to VTGate + +To get VTGate to support TLS use the `--mysql_server_ssl_cert` and `--mysql_server_ssl_key` VTGate options. To require client certificates, you can set `--mysql_server_ssl_ca`, containing the CA certificate you expect the client TLS certificates to be verified against. + +Finally, if you want to require all VTGate clients to only be able to connect using TLS, you can use the `--mysql_server_require_secure_transport` flag. diff --git a/content/en/docs/19.0/reference/features/two-phase-commit.md b/content/en/docs/19.0/reference/features/two-phase-commit.md new file mode 100644 index 000000000..9ebde0d17 --- /dev/null +++ b/content/en/docs/19.0/reference/features/two-phase-commit.md @@ -0,0 +1,102 @@ +--- +title: Two-Phase Commit +weight: 11 +aliases: ['/docs/launching/twopc/','/docs/reference/two-phase-commit/'] +--- + +{{< warning >}} +2PC is an experimental feature and is likely not robust enough to be considered production-ready. +{{< /warning >}} + +{{< info >}} +Transaction commit is much slower when using 2PC. The maintainers of Vitess recommend that you design your VSchema so that cross-shard updates (and 2PC) are not required. +{{< /info >}} + +Vitess 2PC allows you to perform atomic distributed commits. The feature is implemented using traditional MySQL transactions, and hence inherits the same guarantees. With this addition, Vitess can be configured to support the following three levels of atomicity: + +1. **Single database**: At this level, only single database transactions are allowed. Any transaction that tries to go beyond a single database will fail. +2. **Multi database**: A transaction can span multiple databases, but the commit will be best effort. Partial commits are possible. +3. **2PC**: This is the same as Multi-database, but the commit will be atomic. + +2PC commits are more expensive than multi-database because the system has to save away the statements before starting the commit process, and also clean them up after a successful commit. This is the reason why it is a separate option instead of being always on. + +## Isolation + +2PC transactions guarantee atomicity: either the whole transaction commits, or it is rolled back entirely. It does not guarantee Isolation (in the ACID sense). This means that a third party that performs cross-database reads can observe partial commits while a 2PC transaction is in progress. + +Guaranteeing ACID Isolation is very contentious and has high costs. Providing it by default would have made Vitess impractical for the most common use cases. + +### Configuring VTGate + +The atomicity policy is controlled by the `transaction_mode` flag. The default value is `multi` and will set all transactions to multi-database mode. + +To enforce single-database transactions, the VTGates can be started by specifying `transaction_mode=single`. + +To enable 2PC, the VTGates need to be started with `transaction_mode=twopc`. The VTTablets will require additional flags, which will be explained below. + +The VTGate `transaction_mode` flag decides what to allow by default. The application can then override that global default for an individual transaction using `SET transaction_mode="";` when necessary or appropriate. + +## Driver APIs + +The way to request atomicity from the application is driver-specific. + +### MySQL Protocol + +Clients can set the transaction mode via a session-variable: +``` +set transaction_mode='twopc'; +``` + +### gRPC Clients + +#### Go driver + +For the Go driver, you request the atomicity by adding it to the context using the `WithAtomicity` function. For more details, please refer to the respective GoDocs. + +#### Python driver + +For Python, the begin function of the cursor has an optional `single_db` flag. If the flag is `True`, then the request is for a single-db transaction. If `False` (or unspecified), then the following commit call's twopc flag decides if the commit is 2PC or Best Effort (multi). + +#### Adding support in a new driver + +The VTGate RPC API extends the Begin and Commit functions to specify atomicity. The API mimics the Python driver: The BeginRequest message provides a `single_db` flag and the `CommitRequest` message provides an atomic flag which is synonymous to twopc. + +## Configuring VTTablet + +The following flags need to be set to enable 2PC support in VTTablet: + +* **twopc_enable**: This flag needs to be turned on. +* **twopc_coordinator_address**: This should specify the address (or VIP) of the VTGate that VTTablet will use to resolve abandoned transactions. +* **twopc_abandon_age**: This is the time in seconds that specifies how long to wait before asking a VTGate to resolve an abandoned transaction. + +With the above flags specified, every primary VTTablet also turns into a watchdog. If any 2PC transaction is left lingering for longer than `twopc_abandon_age` seconds, then VTTablet invokes VTGate and requests it to resolve it. Typically, the `twopc_abandon_age` needs to be substantially longer than the time it takes for a typical 2PC commit to complete (10s of seconds). + +## Configuring MySQL + +The usual default values of MySQL are sufficient. However, it is important to verify that the `wait_timeout` (28800 seconds by default) has not been changed. If this value was changed to be too short, then MySQL could prematurely kill a prepared transaction causing data loss. + +## Monitoring + +A few additional variables have been added to `/debug/vars`. Failures described below should be rare. But these variables are present so you can build an alert mechanism if anything were to go wrong. + +## Critical failures + +The following errors are not expected to happen. If they do, it means that 2PC transactions have failed to commit atomically: + +* **InternalErrors.TwopcCommit**: This is a counter that shows the number of times a prepared transaction failed to fulfil a commit request. +* **InternalErrors.TwopcResurrection**: This counter is incremented if a new primary failed to resurrect a previously prepared (and unresolved) transaction. + +## Alertable failures + +The following failures are not urgent, but require investigation: + +* **InternalErrors.WatchdogFail**: This counter is incremented if there are failures in the watchdog thread of VTTablet. This means that the watchdog is not able to alert VTGate of abandoned transactions. +* **Unresolved.Prepares**: This is a gauge that is set based on the number of lingering Prepared transactions that have been alive for longer than 5x the abandon age. This usually means that a distributed transaction has repeatedly failed to resolve. A more serious condition is when the metadata for a distributed transaction has been lost and this Prepare is now permanently orphaned. + +## Repairs + +If any of the alerts fire, it is time to investigate. Once you identify the dtid or the VTTablet that originated the alert, you can navigate to the `/twopcz` URL. This will display three lists: + +* **Failed Transactions**: A transaction reaches this state if it failed to commit. The only action allowed for such transactions is that you can discard it. However, you can record the DMLs that were involved and have someone come up with a plan to repair the partial commit. +* **Prepared Transactions**: Prepared transactions can be rolled back or committed. Prepared transactions must be remedied only if their root Distributed Transaction has been lost or resolved. +* **Distributed Transactions**: Distributed transactions can only be Concluded (marked as resolved). diff --git a/content/en/docs/19.0/reference/features/vindexes.md b/content/en/docs/19.0/reference/features/vindexes.md new file mode 100644 index 000000000..386846b51 --- /dev/null +++ b/content/en/docs/19.0/reference/features/vindexes.md @@ -0,0 +1,348 @@ +--- +title: Vindexes +weight: 10 +aliases: ['/docs/schema-management/consistent-lookup/','/docs/reference/vindexes/'] +--- + +## A Vindex maps column values to keyspace IDs + +A Vindex provides a way to map a column value to a `keyspace ID`. Since each shard in Vitess covers a range of `keyspace ID` values, this mapping can be used to identify which shard contains a row. A variety of vindexes are available to choose from with different trade-offs, and you can choose one that best suits your needs. + +The Sharding Key is a concept that was introduced by NoSQL datastores. It is based on the fact that, in NoSQL databases, there is only one access path to the data, which is the Key. However, relational databases are more versatile with respect to the data stored and their relationships. So, sharding a database by only designating a single sharding key is often insufficient. + +If one were to draw an analogy, the indexes in a database would be the equivalent of the key in a NoSQL datastore, except that databases allow multiple indexes per table, and there are many types of indexes. Extending this analogy to a sharded database results in different types of cross-shard indexes. In Vitess, these are called Vindexes. + + +## Advantages + +The advantages of Vindexes stem from their flexibility: + +* A table can have multiple Vindexes. +* Vindexes can be NonUnique, which allows a column value to yield multiple keyspace IDs. +* Vindexes can be a simple function or be based on a lookup table. +* Vindexes can be shared across multiple tables. +* Custom Vindexes can be created and used, and Vitess will still know how to reshard using such Vindexes. + + +### The Primary Vindex + +The Primary Vindex for a table is analogous to a database primary key. Every sharded table must have one defined. A Primary Vindex must be unique: given an input value, it must produce a single keyspace ID. At the time of an insert to the table, the unique mapping produced by the Primary Vindex determines the target shard for the inserted row. Conceptually, this is equivalent to a NoSQL Sharding Key, and we often informally refer to the Primary Vindex as the Sharding Key. + +However, there is a subtle difference: NoSQL datastores allow a choice of the Sharding Key, but the Sharding Strategy or Function is generally hardcoded in the engine. In Vitess, the choice of Vindex allows control of how a column value maps to a keyspace ID. In other words, a Primary Vindex in Vitess not only defines the Sharding Key, but also decides the Sharding Strategy. + +Uniqueness for a Primary Vindex does not mean that the column has to be a primary key or unique key in the MySQL schema for the underlying shard. You can have multiple rows that map to the same keyspace ID. The Vindex uniqueness constraint only ensures that all rows for a keyspace ID end up in the same shard. + +Vindexes come in many varieties. Some of them can be used as Primary Vindex, and others have different purposes. We will describe their properties in the [Predefined Vindexes](#predefined-vindexes) section. + + +### Secondary Vindexes + +Secondary Vindexes are additional vindexes against other columns of a table offering optimizations for WHERE clauses that do not use the Primary Vindex. Secondary Vindexes return a single or a limited set of `keyspace IDs` which will allow VTGate to only target shards where the relevant data is present. In the absence of a Secondary Vindex, VTGate would have to scatter the query to all shards. + +It is important to note that Secondary Vindexes are only used for making routing decisions. The underlying database shards will most likely need traditional indexes on those same columns, to allow efficient retrieval from the table on the underlying MySQL instances. + + +### Unique and NonUnique Vindex + +A Unique Vindex is a vindex that yields at most one keyspace ID for a given input. Knowing that a Vindex is Unique is useful because VTGate can push down certain complex queries into VTTablet if it knows that the scope of that query can be limited to a single shard. Uniqueness is also a prerequisite for a Vindex to be used as Primary Vindex. + +A NonUnique Vindex is analogous to a database non-unique index. It is a secondary index for searching by an alternate WHERE clause. An input value could yield multiple keyspace IDs, and rows could be matched from multiple shards. For example, if a table has a `name` column that allows duplicates, you can define a cross-shard NonUnique Vindex for it, and this will allow an efficient search for users that match a certain `name`. + + +### Functional and Lookup Vindex + +A **Functional Vindex** is a vindex where the column value to keyspace ID mapping is pre-established, typically through an algorithmic function. In contrast, a **Lookup Vindex** is a vindex that provides the ability to create an association between a value and a keyspace ID, and recall it later when needed. Lookup Vindexes are sometimes also informally referred to as cross-shard indexes. + +Typically, the Primary Vindex for a table is Functional. In some cases, it is the identity function where the input value yields itself as the keyspace id. However, other algorithms like a hashing function can also be used. + +A Lookup Vindex is implemented as a MySQL lookup table that maps a column value to the keyspace id. This is usually needed when database user needs to efficiently find a row using a WHERE clause that does not contain the Primary Vindex. At the time of insert, the computed keyspace ID of the row is stored in the lookup table against the column value. + + +### Lookup Vindex types + +The lookup table that implements a Lookup Vindex can be sharded or unsharded. Note that the lookup row is most likely not going to be in the same shard as the keyspace id it points to. + +Vitess allows for the transparent population of these lookup table rows by assigning an owner table, which is the main table that requires this lookup. When a row is inserted into this owner table, the lookup row for it is created in the lookup table. The lookup row is also deleted upon a delete of the corresponding row in the owner table. These essentially result in distributed transactions, which traditionally require 2PC to guarantee atomicity. + +Consistent lookup vindexes use an alternate approach that makes use of careful locking and transaction sequences to guarantee consistency without using 2PC. This gives the best of both worlds, with the benefit of a consistent cross-shard vindex without paying the price of 2PC. To read more about what makes a consistent lookup vindex different from a standard lookup vindex read our [consistent lookup vindexes design documentation](https://github.com/vitessio/vitess/issues/4855). + +There are currently two vindex types in Vitess for consistent lookup: + +* `consistent_lookup_unique` +* `consistent_lookup` + +#### Consistent Lookup usage + +There are 3 sessions which VTGate can open when a consistent lookup is involved. + +1. Pre session +2. Normal session +3. Post session + +The pre and post session are used by lookup queries. The normal session is used by the original query that was sent from the client to VTGate. + +If an insert query is received, insert on consistent lookup will happen through the pre session and the actual query insert will happen through the normal session. When a commit happens it happens on the pre session first and if it succeeds then the commit happens on the post session. + +If an update or delete query is received, the post session is used to do the update or delete on consistent lookup and the normal session for the original query. When a commit happens it happens on the normal session first and if that succeeds then the commit is executed on the post session. + +Anytime there is a consistent lookup involved in the query received, a lock will be taken so that is not available for other sessions to be modified. + +In order to do that we have to select the right session at the beginning. For an insert query, the pre session is used to send `SELECT ...` for the update query. + +For an update or delete query, the post session is used to send `SELECT ...` for the update query. + +Due to this, a current limitation with consistent lookup is that it cannot support an insert followed by an update or delete in the same transaction for the same consistent lookup column value. + +#### Shared Vindexes + +Relational databases encourage normalization, which allows the splitting of data into different tables to avoid duplication in the case of one-to-many relationships. In such cases, a key is shared between the two tables to indicate that the rows are related, a.k.a. `Foreign Key`. + +In a sharded environment, it is often beneficial to keep those rows in the same shard. If a Lookup Vindex was created on the foreign key column of each of those tables, the backing tables would actually be identical. In such cases, Vitess allows sharing a single Lookup Vindex for multiple tables. One of these tables is designated as the owner of the Lookup Vindex, and is responsible for creating and deleting these associations. The other tables just reuse these associations. + +An existing `lookup_unique` vindex can be trivially switched to a `consistent_lookup_unique` by changing the vindex type in the VSchema. This is because the data is compatible. Caveat: If you delete a row from the owner table, Vitess will not perform cascading deletes. This is mainly for efficiency reasons; the application is likely capable of doing this more efficiently. + +As for a `lookup` vindex, it can be changed it to a `consistent_lookup` only if the `from` columns can uniquely identify the owner row. Without this, many potentially valid inserts would fail. + +Functional Vindexes can be also be shared. However, there is no concept of ownership because the column to keyspace ID mapping is pre-established. + +### Lookup Vindex guidance + +The guidance for implementing lookup vindexes has been to create a two-column table. The first column (`from` column) should match the type of the column of the main table that needs the vindex. The second column (`to` column) should be a `BINARY` or a `VARBINARY` large enough to accommodate the keyspace id. + +This guidance remains the same for unique lookup vindexes. + +For non-unique lookup Vindexes, the lookup table should consist of multiple columns. The first column continues to be the input for computing the keyspace IDs. Beyond this, additional columns are needed to uniquely identify the owner row. This should typically be the primary key of the owner table. But it can be any other column that can be combined with the `from` column to uniquely identify the owner row. The last column remains the keyspace ID like before. + +For example, if a user table had the columns `(user_id, email)`, where `user_id` was the primary key and `email` needed a non-unique lookup vindex, the lookup table would have the columns `(email, user_id, keyspace_id)`. + + +### Independence + +The previously described properties are mostly independent of each other. Combining them gives rise to the following valid categories: + +* **Functional Unique**: The most popular category because it is the one best suited to be a Primary Vindex. +* **Functional NonUnique**: There are currently no use cases that need this category. +* **Lookup Unique Owned**: Used for optimizing high QPS read queries that do not use the Primary Vindex columns in their WHERE clause. There is a price to pay: an extra write to the lookup table for insert and delete operations, and an extra lookup for read operations. However, it may be worth it to avoid high QPS read queries to be sent to all shards. The overheard of maintaining the lookup table is amortized as the number of shards grow. +* **Lookup Unique Unowned**: Can be used as an optimization as described in the Shared Vindexes section. +* **Lookup NonUnique Owned**: Used for high QPS queries on columns that are non-unique. +* **Lookup NonUnique Unowned**: You would rarely have to use this category because it is unlikely that you will be using a column as foreign key that is not unique within a shard. But it is theoretically possible. + +Of the above categories, `Functional Unique` and `Lookup Unique Unowned` Vindexes can be a Primary Vindex. This is because those are the only ones that are unique and have the column to keyspace ID mapping pre-established. This is required because the Primary Vindex is responsible for assigning the keyspace ID for a row when it is created. + +However, it is generally not recommended to use a Lookup Vindex as a Primary Vindex because it is too slow for resharding. If absolutely unavoidable, it is recommended to add a `keyspace ID` column to the tables that need this level of control of the row-to-shard mapping. While resharding, Vitess can use that column to efficiently compute the target shard. Vitess can also be configured to auto-populate that column on inserts. This is done using the reverse map feature explained [below](#insert). + +### Defining Vindexes + +Vindexes are defined in the [VSchema](../vschema/) inside the `Vindexes` section of every keyspace. The `column_vindexes` section of each table in that keyspace may refer to the Vindex by name. Here is an example: + +``` json + "name_keyspace_idx": { + "type": "lookup", + "params": { + "table": "name_keyspace_idx", + "from": "name", + "to": "keyspace_id" + }, + "owner": "user" + } +``` + +In the above case, the name of the vindex is `name_keyspace_idx`. It is of type `lookup`, and it is owned by the `user` table. + +Every Vindex has an optional `params` section that contains a map of string key-value pairs. The keys and values differ depending on the vindex type and are explained below. + +There is an optional fourth parameter: `batch_lookup`. To read more about how to use `batch_lookup` see our [Unique Lookup user guide](../../../user-guides/vschema-guide/unique-lookup/). + +### How Vindexes are used + +#### Cost + +Vindexes have costs. For routing a query, the applicable Vindex with the lowest cost is chosen. The current general costs for the different Vindex Types are as follows: + +Vindex Type | Cost +| ----------- | ---- | +| Identity | 0 | +| Functional | 1 | +| Lookup Unique | 10 | +| Lookup NonUnique | 20 | + +#### Select + +In the case of a simple select, Vitess scans the WHERE clause to match references to Vindex columns and chooses the best one to use. If there is no match and the query is simple without complex constructs like aggregates, etc., it is sent to all shards. + +Vitess can handle more complex queries with the new Gen4 planner. + +#### Insert + +* The Primary Vindex is used to generate a keyspace ID. +* The keyspace ID is validated against the rest of the Vindexes on the table. There must exist a mapping from the column value(s) for these Secondary Vindexes to the keyspace ID. +* If a column value was not provided for a Vindex and the Vindex is capable of reverse mapping a keyspace ID to an input value, that function is used to auto-fill the column. If there is no reverse map, it is an error. + +#### Update + +The WHERE clause is used to route the update. Updating the value of a Vindex column is supported, but with a restriction: the change in the column value should not result in the row being moved from one shard to another. A workaround is to perform a delete followed by insert, which works as expected. + +#### Delete + +If the table owns lookup vindexes, then the rows to be deleted are first read and the associated Vindex entries are deleted. Following this, the query is routed according to the WHERE clause. + +#### Ignore Nulls + +There are situations where the from columns of a lookup vindex can be `NULL`. Such columns cannot be inserted in the lookup backing table due to the uniqueness constraints of a lookup. There are two ways to deal with a `NULL` value in the from column of a lookup vindex: + +* Use a predefined vindex as the primary vindex of the backing table that supports the use of a `NULL` value. The table for [predefined vindexes](../vindexes/#predefined-vindexes) lists what types are and are not nullable. +* Enable the `ignore_nulls` option. If the input value of any of the columns is null, Vitess can skip the creation of the lookup row if `ignore_nulls` is enabled. + +{{< info >}} +Note: You can have `NULL` values for the primary vindex column, as long as that vindex allows it (e.g. xxhash). However, you cannot have `NULL` values for the lookup input column, unless you have enabled `ignore_nulls`. +{{< /info >}} + +### Predefined Vindexes + +Vitess provides the following predefined Vindexes: + +Name | Type | Description | Primary | Multi-column | Reversible | Nullable | Cost | Data types | +---- | ---- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------- | ------------ | ---------- | -------- | --- |----------------------------------------------| +binary | Functional Unique | Identity | Yes | No | Yes | Yes | 0 | Any | +binary\_md5 | Functional Unique | MD5 hash | Yes | No | No | Yes | 1 | Any | +consistent\_lookup | Lookup NonUnique | Lookup table non-unique values | No | Identify Row | No | Yes [only if](../vindexes/#ignore-nulls) | 20 | Any | +consistent\_lookup\_unique | Lookup Unique | Lookup table unique values | If unowned | Identify Row | No | Yes [only if](../vindexes/#ignore-nulls) | 10 | Any | +hash | Functional Unique | DES null-key hash | Yes | No | Yes | No | 1 | 64 bit or smaller numeric or equivalent type | +lookup | Lookup NonUnique | Lookup table non-unique values | No | Identify Row | No | Yes [only if](../vindexes/#ignore-nulls) | 20 | Any | +lookup\_unique | Lookup Unique | Lookup table unique values | If unowned | Identify Row | No | Yes [only if](../vindexes/#ignore-nulls) | 10 | Any | +multicol | Functional Unique | Multi-column [subsharding](../../../user-guides/vschema-guide/subsharding-vindex/) hash for use in tenant based sharding or geo-partitioning or multiple column serving as sharding key | Yes | Yes | No | No | sum of cost of hashing function used for each column | Any | +null | Functional Unique | Always map to keyspace ID 0 | Yes | No | No | Yes | 100 | Any | +numeric | Functional Unique | Identity | Yes | No | Yes | No | 0 | 64 bit or smaller numeric or equivalent type | +numeric\_static\_map | Functional Unique | JSON document statically mapping input numeric values to keyspace IDs | Yes | No | No | No | 1 | 64 bit or smaller numeric or equivalent type | +region\_experimental | Functional Unique | Multi-column prefix-based hash for use in geo-partitioning | Yes | Yes | No | No | 1 | String and numeric type | +region\_json | Functional Unique | Multi-column prefix-based hash combined with a JSON map for key-to-region mapping, for use in geo-partitioning | Yes | Yes | No | No | 1 | String and numeric type | +reverse\_bits | Functional Unique | Bit reversal | Yes | No | Yes | No | 1 | 64 bit or smaller numeric or equivalent type | +unicode\_loose\_md5 | Functional Unique | Case-insensitive (UCA level 1) MD5 hash | Yes | No | No | Yes | 1 | String or binary types | +unicode\_loose\_xxhash | Functional Unique | Case-insensitive (UCA level 1) xxHash64 hash | Yes | No | No | Yes | 1 | String or binary types | +xxhash | Functional Unique | xxHash64 hash | Yes | No | No | Yes | 1 | Any | + +Consistent lookup vindexes, as described above, are a new category of Vindexes that are meant to replace the existing lookup Vindexes implementation. For the time being, they have a different name to allow for users to switch back and forth. + +Under the Multi-column heading, an `Identify Row` comment indicates that the Vindex only uses the first column to map to the keyspace id(s). The rest of the columns are used to identify the owner row. + +Lookup Vindexes support the following parameters: + +* `table`: The backing table for the lookup vindex. It is recommended that the table name be qualified by its keyspace. +* `from`: The list of "from" columns. The first column is used for routing, and the rest of the columns are used for identifying the owner row. +* `to`: The name of the "to" keyspace\_id column. +* `autocommit` (false): if true, specific vindex entries are updated in their own autocommit transaction. This is useful if values never get remapped to different values. For example, if the input column comes from an auto-increment value. Note that the autocommit option does not affect `consistent_lookup` or `consistent_lookup_unique` vindexes, but is for use with `lookup` or `lookup_unique` vindexes. +* `write_only` (false): if true, the vindex is kept updated, but a lookup will return all shards if the key is not found. This mode is used while the vindex is being populated and backfilled. +* `no_verify` (false): if true, Vitess will not internally verify lookup results. This mode is a performance optimization that is unsafe to use unless the `from` columns in the `owner` table rows are never updated. +* `read_lock` (exclusive): determines the type of locking read Vitess uses when querying the backing table. Valid options are `exclusive` (translates to a MySQL `FOR UPDATE` lock), `shared` (`LOCK IN SHARE MODE`) or `none`. Relaxing the default (`exclusive`) may improve performance, but is unsafe if concurrent queries can select and delete the same rows from the backing table. +* `ignore_nulls` (false): if true, null values in input columns do not create entries in the lookup table. Otherwise, a null input results in an error. + +The `numeric_static_map` supports the following parameters: + + * `json_path`: Path to a file which must contain a JSON document that maps input numeric values to keyspace ids. + * `json`: A string which must contain a JSON document that maps input numeric values to keyspace ids. + * `fallback_type`: Name of a functional vindex, e.g. `xxhash`, to fallback to when looking up a key not present in the map. + +One of either `json_path` or `json` is required. The two are mutually exclusive. + +The `region_experimental` vindex is an experimental vindex that uses the first one or two bytes of the input value as prefix for keyspace id. The rest of the bits are hashed. This allows you to group users of the same region within the same group of shards. The vindex requires a `region_bytes` parameter that specifies if the prefix is one or two bytes. + +The `region_json` vindex requires an additional `region_map` file name that is used to compute the region from the country. The `region_bytes` is presumed to contain country codes. + +Custom Vindexes can also be created as needed. At the moment there is no formal plugin system for custom Vindexes, but the interface is well-defined, and thus custom implementations including code performing arbitrary lookups in other systems can be accommodated. + +\ +\ +There are also the following legacy (deprecated) Vindexes. **Do not use these**: + +| Name | Type | Primary | Reversible | Cost | +| ---- | ---- | ------- | ---------- | ---- | +| lookup\_hash | Lookup NonUnique | No | No | 20 | +| lookup\_hash\_unique | Lookup Unique | If unowned | No | 10 | +| lookup\_unicodeloosemd5\_hash | Lookup NonUnique | No | No | 20 | +| lookup\_unicodeloosemd5\_hash\_unique | Lookup Unique | If unowned | No | 10 | + +### Query Vindex functions + +You can query Vindex functions to see the resulting `keyspace_id` it produces (the resulting hash is a 64-bit hexadecimal number) and thus which shard a particular row would be placed on within the keyspace. You would query the Vindex functions by referencing their name as defined in your VSchema, and using query predicates specifically on the fixed name `id` field (this is not related to your actual schema). The Vindex functions support both equality (`WHERE id = X`) and list (`WHERE id IN(...)`) lookups. Here's a full example using the `customer` keyspace: + +First, a snippet of the VSchema: +``` shell +$ vtctlclient -server=localhost:15999 GetVSchema customer | jq '.vindexes' +{ + "binary_md5_vdx": { + "type": "binary_md5" + }, + "binary_vdx": { + "type": "binary" + }, + "hash_vdx": { + "type": "hash" + } +} +``` + +And example queries using them from a VTGate (the Vindex function exists as a meta table in the given keyspace): +``` sql +mysql> use customer; +Database changed + +mysql> select * from hash_vdx where id in(1,29999,397)\G +*************************** 1. row *************************** + id: 1 + keyspace_id: k@�J�K� + range_start: + range_end: � +hex_keyspace_id: 166b40b44aba4bd6 + shard: -80 +*************************** 2. row *************************** + id: 29999 + keyspace_id: ��>V�7M� + range_start: � + range_end: +hex_keyspace_id: fcd63e56d3374d88 + shard: 80- +*************************** 3. row *************************** + id: 397 + keyspace_id: U��s��� + range_start: + range_end: � +hex_keyspace_id: 5584fa738baaf516 + shard: -80 +3 rows in set (0.00 sec) + +mysql> select * from binary_md5_vdx where id = "heythere"\G +*************************** 1. row *************************** + id: heythere + keyspace_id: ��, +���e��u�I� + range_start: � + range_end: +hex_keyspace_id: d9e62c0ad204fe91658ecc758049e515 + shard: 80- +1 row in set (0.00 sec) + +``` + +### Unknown Vindex parameters + +Most Vindexes will accept unknown parameters without complaint. For example, the following `lookup` Vindex can be applied without error: + +```json + "name_keyspace_idx": { + "type": "lookup", + "params": { + "table": "name_keyspace_idx", + "from": "name", + "to": "keyspace_id", + "rear_lock": "none" + }, + "owner": "user" + } +``` + +In this example, the user intended to use `read_lock` but typed `rear_lock` by mistake. They will be in for an unpleasant surprise during the traffic peak and `rear_lock` does nothing to mitigate lock contention. + +To help users avoid these kinds of unpleasant surprises, Vindexes may expose unknown parameters in the following ways: + + * [As warnings](../../programs/vtctl/schema-version-permissions/#warnings) in the output of `ApplyVSchema`. + * As a [VTGate stat](../../../user-guides/configuration-basic/monitoring/#vindexunknownparameters) named `VindexUnknownParameters`. diff --git a/content/en/docs/19.0/reference/features/vitess-sequences.md b/content/en/docs/19.0/reference/features/vitess-sequences.md new file mode 100644 index 000000000..7803cd8be --- /dev/null +++ b/content/en/docs/19.0/reference/features/vitess-sequences.md @@ -0,0 +1,241 @@ +--- +title: Sequences +weight: 3 +aliases: ['/docs/reference/vitess-sequences/'] +--- + +This document describes the Vitess Sequences feature, and how to use it. + +## Motivation + +MySQL provides the `auto_increment` feature to assign monotonically incrementing +IDs to a column in a table. However, when a table is sharded across multiple +instances, maintaining the same feature is a lot more tricky. + +Vitess Sequences fill that gap: + +* Inspired from the usual SQL sequences (implemented in different ways by + Oracle, SQL Server and PostgreSQL). + +* Very high throughput for ID creation, using a configurable in-memory block allocation. + +* Transparent use, similar to MySQL `auto_increment`: when the field is omitted in + an `insert` statement, the next sequence value is used. + +## When *not* to use `auto_increment` + +Let us start by exploring the limitations and drawbacks of using an +`auto_increment` column. + +### Security Considerations + +Using `auto_increment` can leak confidential information about a service. Take +the example of a web site that store user information, and assign user IDs +to its users as they sign in. The user ID is then passed in a cookie for all +subsequent requests. + +The client then knows their own user ID. It is now possible to: + +* Try other user IDs and expose potential system vulnerabilities. + +* Get an approximate number of users of the system (using the user ID). + +* Get an approximate number of sign-ups during a week (creating two accounts a + week apart, and diffing the two IDs). + +Auto-incrementing IDs should be reserved for either internal applications, or +exposed to the clients only when safe. + +### Alternatives + +Alternative to auto-incrementing IDs are: + +* Using a 64 bit random generator number. Try to insert a new row with that + ID. If already taken (the statement returns an integrity error), try another + ID. + +* Using a UUID scheme, and generate truly unique IDs. + +Now that this is out of the way, let's examine the specifics of +[MySQL auto_increment](https://dev.mysql.com/doc/refman/en/example-auto-increment.html). + +## MySQL `auto_increment` Feature + +Comparing `auto_increment` features, properties, and behaviors that Vitess Sequences share: + +* A row that has no value provided for the `auto_increment` column will be given the next ID. + +* The current ID value is stored in table metadata. + +* Values may be ‘burned’ (by rolled back transactions) and gaps in the generated and stored values are possible. + +* The value stored by the primary instance resulting from the original statement is sent in the replication stream, + so replicas will have the same value when re-playing the stream. + +* There is no strict guarantee about ordering: two concurrent statements may + have their commit time in one order, but their auto-incrementing ID in the + opposite order (as the value for the ID is reserved when the statement is + issued, not when the transaction is committed). + +* When inserting a row in a table with an `auto_increment` column, if the value + for the `auto_increment` column is generated (not explicitly specified in the + statement), the value for the column is returned to the client alongside the + statement result (which can be queried with [`LAST_INSERT_ID()`](https://dev.mysql.com/doc/refman/en/information-functions.html#function_last-insert-id)). + +## Vitess Sequences + +Each sequence has a backing MySQL table — which **must** be in an unsharded keyspace — and +uses a single row in that table to describe which values the sequence should have next. +To improve performance we also support block allocation of IDs: each update to +the MySQL table is only done every N IDs (N being configurable) and in between those writes +only the in-memory structures within the primary vttablet serving the unsharded keyspace +where the backing table lives are updated, making the QPS only limited by the RPC latency +between the vtgates and the the serving vttablet for the sequence table. + +So the sequence table is an unsharded single row table that Vitess can use to generate monotonically increasing ids. +The VSchema then allows you to associate a column in your table with the sequence. Once they are associated, an `insert` +on that table will transparently fetch an ID from the sequence, fill in the value, and route the row to the appropriate shard. + +### Creating a Sequence + +To create a sequence, a backing table must first be created. The table structure must have +the following columns and SQL comment in order to provide sequences (in the examples here the sequence is for a user table): + +``` sql +create table user_seq(id bigint, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +``` + +

+{{< info >}} +Note: the vttablet in-memory structure uses `int64` types so `bigint unsigned` types are not supported for these columns in the backing table +{{< /info >}} +

+ +Then the sequence has to be defined in the VSchema for the unsharded keyspace where the backing table lives: + +``` json +{ + "sharded": false, + "tables": { + "user_seq": { + "type": "sequence" + }, + ... + } +} +``` + +

+Now any table that will be using the new sequence can reference it in its VSchema as shown here: +

+ +``` json +{ + ... + "tables" : { + "user": { + "column_vindexes": [ + ... + ], + "auto_increment": { + "column": "user_id", + "sequence": "user_seq" + } + }, +``` + +## Initializing a Sequence +The sequence backing table needs to be pre-populated with a single row where: + +* `id` must always be 0. +* `next_id` should be set to the next (starting) value of the sequence. +* `cache` is the number of values to be reserved and cached in each block allocation of IDs served by the primary vttablet of the +unsharded keyspace where the sequence backing table lives. This value should be set to a fairly large number like 1000 for improved write +latency and throughput (the tradeoff being that this chunk of reserved IDs could be lost if e.g. the tablet crashes, resulting in a +potential ID gap up to that size). + +For example: + +``` sql +insert into user_seq(id, next_id, cache) values(0, 1, 1000); +``` + +### Accessing a Sequence directly + +If a sequence is used to fill in an ID column for a table, nothing further needs to +be done. Just sending no value for the column will make vtgate insert the next +sequence value in its place. + +It is also possible, however, to access the sequence directly with the following SQL constructs: + +``` sql +/* Returns the next value for the sequence */ +select next value from user_seq; + +/* Returns the next value for the sequence, and also reserve 4 values after that. */ +select next 5 values from user_seq; +``` + +### Sequence limitations + +Vitess sequences do not behave like a MySQL `auto_increment` column in all +ways. One significant example is if you mix cases where you provide values +for the auto-incrementing column, and cases where you do not. In a case +like this, a MySQL `auto_increment` will keep track of the highest value you +have used, and thus what the "next" value for the column would be. Vitess +sequences do not do this. Here is an example: + +MySQL mixed insert case (`c1` is the auto-incrementing column): +``` sql +mysql> create table t1 (c1 bigint not null auto_increment, c2 bigint default null, primary key (c1)) engine=innodb; +Query OK, 0 rows affected (0.03 sec) + +mysql> insert into t1 (c1,c2) values (1,1),(2,2),(3,3); +Query OK, 3 rows affected (0.01 sec) +Records: 3 Duplicates: 0 Warnings: 0 + +mysql> insert into t1 (c2) values (4); +Query OK, 1 row affected (0.01 sec) + +mysql> select * from t1; ++----+------+ +| c1 | c2 | ++----+------+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | +| 4 | 4 | ++----+------+ +4 rows in set (0.00 sec) +``` + + +Vitess sequence mixed insert case (`c1` is the sequence column): +``` sql +mysql> insert into t1 (c1,c2) values (1,1),(2,2),(3,3); +Query OK, 3 rows affected (0.04 sec) + +mysql> select * from t1; ++----+------+ +| c1 | c2 | ++----+------+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | ++----+------+ +3 rows in set (0.01 sec) + +mysql> insert into t1 (c2) values (4); +ERROR 1062 (23000): transaction rolled back to reverse changes of partial DML execution: target: sharded.-80.primary: vttablet: Duplicate entry '1' for key 't1.PRIMARY' (errno 1062) (sqlstate 23000) (CallerID: user): Sql: "insert into t1(c2, c1) values (:_c2_0, :_c1_0)", BindVars: {__seq0: "type:INT64 value:\"1\""_c1_0: "type:INT64 value:\"1\""_c2_0: "type:INT64 value:\"4\""vtg1: "type:INT64 value:\"4\""} +mysql> select * from t1; ++----+------+ +| c1 | c2 | ++----+------+ +| 1 | 1 | +| 2 | 2 | +| 3 | 3 | ++----+------+ +3 rows in set (0.01 sec) +``` + +It is arguably bad practice to mix use-cases like this. If you avoid mixing use-cases you will not run into this issue. diff --git a/content/en/docs/19.0/reference/features/vschema.md b/content/en/docs/19.0/reference/features/vschema.md new file mode 100644 index 000000000..5ee352292 --- /dev/null +++ b/content/en/docs/19.0/reference/features/vschema.md @@ -0,0 +1,311 @@ +--- +title: VSchema +weight: 9 +aliases: ['/docs/schema-management/vschema/','/docs/reference/vschema/'] +--- + +## Overview + +VSchema stands for Vitess Schema. It is an abstraction layer that presents a unified view of the underlying keyspaces and shards, and gives the semblance of a single MySQL server. + +For example, VSchema will contain the information about the sharding key for a sharded table. When the application issues a query with a WHERE clause that references the key, the VSchema information will be used to route the query to the appropriate shard. + +## Architecture + +The VSchema is specified on a per-keyspace basis. Additionally, a separate set of RoutingRules can be specified. This information is stored in the global topology. A vtctld `RebuildVSchemaGraph` command combines the RoutingRules and the per-keyspace VSchemas into a unified data structure called SrvVSchema, which is deployed into the topo of each cell. The VTGates consume this information, which they use for planning and routing queries from the application. + +![VSchema Architecture](../img/vschema_arch.png) + +## Database Access Model + +A Vitess Keyspace is the logical equivalent to a MySQL database. The usual syntax used to access databases in mysql work in Vitess as well. For example, you can connect to a specific database by specifying the database name in the connection parameter. You can also change the database you are connected to through the `use` statement. While connected to a database, you can access a table from a different keyspace by qualifying the table name in your query, like `select * from other_keyspace.table`. + +### Tablet Types + +Unlike MySQL, the vitess servers unify all types of mysql servers. You can ask vitess to target a specific tablet type by qualifying it as part of the database name. For example, to access replica tablets, you may specify the database name as `keyspace@replica`. This name can also be specified in the connection string. If no tablet type is specified in the database name, then the value specified in VTGate's `--default_tablet_type` flag is used. + +### Unspecified Mode + +Additionally, you can connect without specifying a database name and still access tables without qualifying them by their keyspace. If the table name is unique across all keyspaces, then VTGate automatically sends the query to the associated keyspace. Otherwise, it returns an error. This mode is useful if you start off with a single keyspace and plan on splitting it into multiple parts. + +You can still specify a tablet type for the unspecified mode. For example, you can connect to `@replica` if you want to access the replica tablets in unspecified mode. + +Some frameworks require you to specify an explicit database name while connecting. In order to make them work in unspecified mode, you can specify the database name as `@replica` or `@primary` instead of a blank one. + +## Sharded keyspaces require a VSchema + +A VSchema is needed to tie together all the databases that Vitess manages. For a very trivial setup where there is only one unsharded keyspace, there is no need to specify a VSchema because Vitess will know that there is no other place to route a query. + +If you have multiple unsharded keyspaces, you can still avoid defining a VSchema in one of two ways: + +1. Connect to a keyspace and all queries are sent to it. +2. Connect to Vitess without specifying a keyspace (unspecified mode), but use qualified names for tables, like `keyspace.table` in your queries. + +However, once the setup exceeds the above complexity, VSchemas become a necessity. Vitess has a [working demo](https://github.com/vitessio/vitess/tree/main/examples/demo) of VSchemas. + +## Sharding Model + +In Vitess, a `keyspace` is sharded by `keyspace ID` ranges. Each row is assigned a keyspace ID, which acts like a street address, and it determines the shard where the row lives. In some respect, one could say that the `keyspace ID` is the equivalent of a NoSQL sharding key. However, there are some differences: + +1. The `keyspace ID` is a concept that is internal to Vitess. The application does not need to know anything about it. +2. There is no physical column that stores the actual `keyspace ID`. This value is computed as needed. + +This difference is significant enough that we do not refer to the keyspace ID as the sharding key. A [Primary Vindex](../vindexes/#the-primary-vindex) more closely resembles the NoSQL sharding key. + +Mapping to a `keyspace ID`, and then to a shard, gives us the flexibility to reshard the data with minimal disruption because the `keyspace ID` of each row remains unchanged through the process. + +## Vindexes + +The Vschema contains the [Vindex](../vindexes) for any sharded tables. The Vindex tells Vitess where to find the shard that contains a particular row for a sharded table. Every VSchema must have at least one Vindex, called the [Primary Vindex](../vindexes/#the-primary-vindex), defined. The Primary Vindex is unique: given an input value, it produces a single keyspace ID, or value in the keyspace used to shard the table. The Primary Vindex is typically a functional Vindex: Vitess computes the keyspace ID as needed from a column in the sharded table. + +## Sequences + +Auto-increment columns do not work very well for sharded tables. [Vitess sequences](../vitess-sequences) solve this problem. Sequence tables must be specified in the VSchema, and then tied to table columns. At the time of insert, if no value is specified for such a column, VTGate will generate a number for it using the sequence table. + +## Reference tables + +Vitess allows you to create an unsharded table and deploy it into all shards of a sharded keyspace. The data in such a table is assumed to be identical for all shards. In this case, you can specify that the table is of type `reference`, and should not specify any vindex for it. Any joins of this table with an unsharded table will be treated as a local join. + +Typically, such a table has a canonical source in an unsharded keyspace, and the copies in the sharded keyspace are kept up-to-date through VReplication. + + +## Per-Keyspace VSchema + +The VSchema uses a flexible proto JSON format. Essentially, you can use `snake_case` or `camelCase` for the keys. + +The configuration of your VSchema reflects the desired sharding configuration for your database, including whether or not your tables are sharded and whether you want to implement a secondary Vindex. + +### Commands + +You can use the following commands for maintaining the VSchema: + +* `GetVSchema ` +* `ApplyVSchema -- {--vschema= || --vschema_file= || --sql= || --sql_file=} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run] ` +* `RebuildVSchemaGraph [--cells=c1,c2,...]` +* `GetSrvVSchema ` +* `DeleteSrvVSchema ` + +In order to verify that a VTGate has loaded SrvVSchema correctly, you can visit the `/debug/vschema` URL on the VTGate's http port. + +### Unsharded Table + +The following snippets show the necessary configs for creating a table in an unsharded keyspace: + +Schema: + +``` sql +# lookup keyspace +create table name_user_idx(name varchar(128), user_id bigint, primary key(name, user_id)); +``` + +VSchema: + +``` json +// lookup keyspace +{ + "sharded": false, + "tables": { + "name_user_idx": {} + } +} +``` + +For a normal unsharded table, the VSchema only needs to know the table name. No additional metadata is needed. + +### Sharded Table With Simple Primary Vindex + +To create a sharded table with a simple [Primary Vindex](../vindexes/#the-primary-vindex), the VSchema requires more information: + +Schema: + +``` sql +# user keyspace +create table user(user_id bigint, name varchar(128), primary key(user_id)); +``` + +VSchema: + +``` json +// user keyspace +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "user": { + "column_vindexes": [ + { + "column": "user_id", + "name": "hash" + } + ] + } + } +} +``` + +Because Vindexes can be shared, the JSON requires them to be specified in a separate `vindexes` section, and then referenced by name from the `tables` section. The VSchema above simply states that `user_id` uses `hash` as Primary Vindex. The first Vindex of every table must be the Primary Vindex. + +### Specifying A Sequence + +Since user is a sharded table, it will be beneficial to tie it to a Sequence. However, the sequence must be defined in the lookup (unsharded) keyspace. It is then referred from the user (sharded) keyspace. In this example, we are designating the `user_id` (Primary Vindex) column as the auto-increment. + +Schema: + +``` sql +# lookup keyspace +create table user_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into user_seq(id, next_id, cache) values(0, 1, 3); +``` + +For the sequence table, `id` is always 0. `next_id` starts off as 1, and the cache is usually a medium-sized number like 1000. In our example, we are using a small number to demonstrate how it works. + +VSchema: + +``` json +// lookup keyspace +{ + "sharded": false, + "tables": { + "user_seq": { + "type": "sequence" + } + } +} + +// user keyspace +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "user": { + "column_vindexes": [ + { + "column": "user_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "user_id", + "sequence": "lookup.user_seq" + } + } + } +} +``` + +If necessary, the reference to the sequence table `lookup.user_seq` can be escaped using backticks. + +### Specifying A Secondary Vindex + +The following snippet shows how to configure a [Secondary Vindex](../vindexes/#secondary-vindexes) that is backed by a lookup table. In this case, the lookup table is configured to be in the unsharded lookup keyspace: + +Schema: + +``` sql +# lookup keyspace +create table name_user_idx(name varchar(128), user_id bigint, primary key(name, user_id)); +``` + +VSchema: + +``` json +// lookup keyspace +{ + "sharded": false, + "tables": { + "name_user_idx": {} + } +} + +// user keyspace +{ + "sharded": true, + "vindexes": { + "name_user_idx": { + "type": "lookup", + "params": { + "table": "name_user_idx", + "from": "name", + "to": "user_id" + }, + "owner": "user" + } + }, + "tables": { + "user": { + "column_vindexes": [ + { + "column": "name", + "name": "name_user_idx" + } + ] + } + } +} +``` + +To recap, a checklist for creating the shared Secondary Vindex is: + +* Create physical `name_user_idx` table in lookup database. +* Define a routing for it in the lookup VSchema. +* Define a Vindex as type `lookup` that points to it. Ensure that the `params` match the table name and columns. +* Define the owner for the Vindex as the `user` table. +* Specify that `name` uses the Vindex. + +Currently, these steps have to be currently performed manually. However, extended DDLs backed by improved automation will simplify these tasks in the future. + +### The columns field + +For a table, you can specify an additional columns field. This can be used for two purposes: + +* Specifying that a column contains text. If so, the VTGate planner can rewrite queries to leverage mysql’s collation where possible. +* If the full list of columns is specified, then VTGate can resolve columns to their tables where needed, and also authoritative expand column lists, like in the case of a `select *` or `insert` statements with no column list. + +Here is an example: + +``` json + "tables": { + "user": { + "column_vindexes": [ + { + "column": "name", + "name": "name_user_idx" + } + ], + "columns": [ + { + "name": "name", + "type": "VARCHAR" + }, + { + "name": "keyspace_id", + "type": "VARBINARY" + } + ], + "column_list_authoritative": true + } + } +``` + +If a query goes across multiple shards and ordering is needed on the `name` column that is now specified as `VARCHAR`, then VTGate will leverage mysql to additionally the `weigh_string` of that column and use that value to order the merged results. + +If `column_list_authoritative` is false or not specified, then VTGate will treat the list of columns as partial and will not automatically expand open-ended constructs like `select *`. + +Vtgates also have the capability to track the schema changes and populate the columns list on its own. To know more about this feature, read [here](../schema-tracking). + +### Advanced usage + +The examples/demo also shows more tricks you can perform: + +* The `music` table uses a secondary lookup vindex `music_user_idx`. However, this lookup vindex is itself a sharded table. +* `music_extra` shares `music_user_idx` with `music`, and uses it as Primary Vindex. +* `music_extra` defines an additional Functional Vindex called `keyspace_id` which the demo auto-populates using the reverse mapping capability. +* There is also a `name_info` table that showcases a case-insensitive Vindex `unicode_loose_md5`. diff --git a/content/en/docs/19.0/reference/features/vtgate-buffering.md b/content/en/docs/19.0/reference/features/vtgate-buffering.md new file mode 100644 index 000000000..6e831a2e8 --- /dev/null +++ b/content/en/docs/19.0/reference/features/vtgate-buffering.md @@ -0,0 +1,164 @@ +--- +title: VTGate Buffering +weight: 5 +aliases: ['/docs/user-guides/buffering/','/docs/reference/programs/vtgate'] +--- + +VTGate in Vitess supports the **buffering** of queries in certain situations. +The original intention of this feature was to **reduce**, not necessarily +eliminate, downtime during planned fail overs PlannedReparentShard (PRS). VTGate +has been extended to provide buffering in some additional fail over situations, +e.g. during resharding. + +Note that buffering is not intended for, nor active during, unplanned failovers +or other unplanned issues with a `PRIMARY` tablet during normal operations. +There are some new heuristics built in the `keyspace_events` implementation +for scenarios where the `PRIMARY`is offline. However, you should not rely on +these at this time. + +Buffering can be somewhat involved, and there are a number of tricky edge cases. +We will discuss these in the context of an application's experience, starting +with the simplest case: that of buffering during a PRS (PlannedReparentShard) +operation. Examples of various edge cases can be found in +[Buffering Scenarios](../../../user-guides/configuration-advanced/buffering-scenarios/). + +## VTGate flags to enable buffering + +First, let us cover the flags that need to be set in VTGate to enable +buffering: + + * `--enable_buffer`: Enables buffering. **Not enabled by default** + * `--enable_buffer_dry_run`: Enable logging of if/when buffering would + trigger, without actually buffering anything. Useful for testing. + Default: `false` + * `--buffer_implementation`: Default: `keyspace_events`. More consistent results + have been seen with `keyspace_events`. However, if the legacy behavior is needed + you may use `healthcheck`. + * `--buffer_size`: Default: `1000` This should be sized to the appropriate + number of expected request during a buffering event. Typically, if each + connection has one request then, each connection will consume one buffer slot + of the `buffer_size` and be put in a "pause" state as it is buffered on the + vtgate. The resource consideration for setting this flag are memory resources. + * `--buffer_drain_concurrency`: Default: `1`. If the buffer is of any + significant size, you probably want to increase this proportionally. + * `--buffer_keyspace_shards`: Can be used to limit buffering to only + certain keyspaces. Should not be necessary in most cases, defaults to watching + all keyspaces. + * `--buffer_max_failover_duration`: Default: `20s`. If buffering is active + longer than this set duration, stop buffering and return errors to the client. + * `--buffer_window`: Default: `10s`. The maximum time any individual request + should be buffered for. Should probably be less than the value for + `--buffer_max_failover_duration`. Adjust according to your application + requirements. Be aware, if your MySQL client has `write_timeout` or + `read_timeout` settings those values should be greater than the + `buffer_max_failover_duration`. + * `--buffer_min_time_between_failovers`: Default `1m`. If consecutive + fail overs for a shard happens within less than this duration, do **not** + buffer again. The purpose of this setting is to avoid consecutive fail over + events where vtgate may be buffering, but never purging the buffer. + +## Types of queries that can be buffered + + * Only requests to tablets of type `PRIMARY` are buffered. In-flight requests + to a `REPLICA` in the process of transitioning to `PRIMARY` because of a PRS + should be unaffected, and do not require buffering. + +## What happens during a PlannedReparentShard with Buffering + +Fundamentally Vitess will: + + * Hold up and buffer any queries sent to the `PRIMARY` tablet for a shard. + * Wait for replication on a primary candidate `REPLICA` to catch up to the + current `PRIMARY`. + * Perform the actions which demote the `PRIMARY` to a `REPLICA` and promote a + primary candidate `REPLICA` to `PRIMARY`. + * Drain the buffered queries to the new `PRIMARY` tablet. + * Begin the countdown timer for `buffer_max_failover_duration`. + + {{< warning >}} +This process is not guaranteed to eliminate errors to the application, but +rather reduce them or make them less frequent. The application should still +endeavor to handle errors appropriately if/when they occur (e.g. unplanned +outages/fail overs, etc.) +{{< /warning >}} + + +## How does it work? + +The following steps are considerably simplified, but to give a high level +overview of how buffering works: + + * All buffering is done in `vtgate` + * When a shard begins a fail over or resharding event, and a query is sent + from `vtgate` to `vttablet`, `vttablet` will return a certain type of error + to `vtgate` (`vtrpcpb.Code_CLUSTER_EVENT`). + * This error indicates to `vtgate` that it is appropriate to buffer this + request. + * Separately the various timers associated with the flags above are being + maintained to timeout and return errors to the application when appropriate, + e.g. if an individual request was buffered for too long; or if buffering + start "too long" ago. + * When the failover is complete, and the tablet starts accepting queries + again, we start draining the buffered queries, with a concurrency as + indicated by the `buffer_drain_concurrency` value. + * When the buffer is drained, the buffering is complete. We maintain a + timer based on `buffer_min_time_between_failovers` to make sure we + do not buffer again if another fail over starts within that period. + + +## What the application sees + +When buffering executes as expected the application will see a pause in their +query processing. Each query will consume a slot from the configured +`buffer_size` and will be paused for the duration of `buffer_window` before +errors are returned. Once the failover event completes, the buffer will begin to +drain at a concurrency set by the `buffer_drain_concurrency` value. Next a +countdown timer will start set by `buffer_min_time_between_failovers`. During +this period any future buffers will be disabled. Once the +`buffer_min_time_between_failovers` timer expires, buffering will be enabled +once again. + +## Potential Errors + +Buffering was implemented to minimize downtime, but there is still potential for +errors to occur, and your application should be configured to handle them +appropriately. Below are a few errors which may occur: + +### Lost connection + +``` +Error Number: 2013 +Error Message: Lost connection to MySQL server during query (timed out) +``` + +Due to the nature of buffering and pausing your queries the MySQL client will see +delays in their query request. If your client has a `read_timeout` or +`write_timeout` set, the value should be greater than the `buffer_window` value set +in vtgate. + +### Primary not serving + +``` +Error Number: 1105 +Error Message: target: ${KEYSPACE}.0.primary: primary is not serving, there is a reparent operation in progress +``` + +This is the most common error you will see in regards to buffering. You may get +this result in the application for a variety of reasons: + +* `enable_buffer` is not configured; by default buffers are disabled. +* `enable_buffer_dry_run` is configured to be true; no buffering actions are +taken when this setting is enabled. +* `buffer_keyspace_shards` is not configured for the keyspace on which the +PRS event is being executed. +* `buffer_size` is set to be lower than the number of incoming queries; any +incoming request over the `buffer_size` will see this error. +* A new buffering event occurs before the `buffer_min_time_between_fail overs` +has expired. +* `buffer_max_failover_duration` has been exceeded; buffering is discontinued +and this error is returned. + +## Next Steps + +You may want to review the scenarios in +[Buffering Scenarios](../../../user-guides/configuration-advanced/buffering-scenarios/). diff --git a/content/en/docs/19.0/reference/img/vitesstransportsecuritymodel.png b/content/en/docs/19.0/reference/img/vitesstransportsecuritymodel.png new file mode 100644 index 000000000..0909a9740 Binary files /dev/null and b/content/en/docs/19.0/reference/img/vitesstransportsecuritymodel.png differ diff --git a/content/en/docs/19.0/reference/programs/_index.md b/content/en/docs/19.0/reference/programs/_index.md new file mode 100644 index 000000000..5b1bea58b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/_index.md @@ -0,0 +1,7 @@ +--- +title: Programs +description: Reference documents for list of Vitess programs +notoc: true +weight: 4 +--- + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/_index.md b/content/en/docs/19.0/reference/programs/mysqlctl/_index.md new file mode 100644 index 000000000..bf8692ed9 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/_index.md @@ -0,0 +1,106 @@ +--- +title: mysqlctl +series: mysqlctl +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## mysqlctl + +mysqlctl initializes and controls mysqld with Vitess-specific configuration. + +### Synopsis + +`mysqlctl` is a command-line client used for managing `mysqld` instances. + +It is responsible for bootstrapping tasks such as generating a configuration file for `mysqld` and initializing the instance and its data directory. +The `mysqld_safe` watchdog is utilized when present. +This helps ensure that `mysqld` is automatically restarted after failures. + +### Options + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + -h, --help help for mysqlctl + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl init](./mysqlctl_init/) - Initializes the directory structure and starts mysqld. +* [mysqlctl init_config](./mysqlctl_init_config/) - Initializes the directory structure, creates my.cnf file, but does not start mysqld. +* [mysqlctl position](./mysqlctl_position/) - Compute operations on replication positions +* [mysqlctl reinit_config](./mysqlctl_reinit_config/) - Reinitializes my.cnf file with new server_id. +* [mysqlctl shutdown](./mysqlctl_shutdown/) - Shuts down mysqld, without removing any files. +* [mysqlctl start](./mysqlctl_start/) - Starts mysqld on an already 'init'-ed directory. +* [mysqlctl teardown](./mysqlctl_teardown/) - Shuts mysqld down and removes the directory. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_init.md b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_init.md new file mode 100644 index 000000000..95e88b6a4 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_init.md @@ -0,0 +1,118 @@ +--- +title: init +series: mysqlctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## mysqlctl init + +Initializes the directory structure and starts mysqld. + +### Synopsis + +Bootstraps a new `mysqld` instance, initializes its data directory, and starts the instance. +The MySQL version and flavor will be auto-detected, with a minimal configuration file applied. + +``` +mysqlctl init [flags] +``` + +### Examples + +``` +mysqlctl \ + --alsologtostderr \ + --tablet_uid 101 \ + --mysql_port 12345 \ + init +``` + +### Options + +``` + -h, --help help for init + --init_db_sql_file string Path to .sql file to run after mysqld initiliaztion. + --wait_time duration How long to wait for mysqld startup. (default 5m0s) +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl](../) - mysqlctl initializes and controls mysqld with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_init_config.md b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_init_config.md new file mode 100644 index 000000000..2dc560a10 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_init_config.md @@ -0,0 +1,116 @@ +--- +title: init config +series: mysqlctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## mysqlctl init_config + +Initializes the directory structure, creates my.cnf file, but does not start mysqld. + +### Synopsis + +Bootstraps the configuration for a new `mysqld` instance and initializes its data directory. +This command is the same as `init` except the `mysqld` server will not be started. + +``` +mysqlctl init_config [flags] +``` + +### Examples + +``` +mysqlctl \ + --alsologtostderr \ + --tablet_uid 101 \ + --mysql_port 12345 \ + init_config +``` + +### Options + +``` + -h, --help help for init_config +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl](../) - mysqlctl initializes and controls mysqld with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_position.md b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_position.md new file mode 100644 index 000000000..b259123fd --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_position.md @@ -0,0 +1,101 @@ +--- +title: position +series: mysqlctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## mysqlctl position + +Compute operations on replication positions + +``` +mysqlctl position [flags] +``` + +### Options + +``` + -h, --help help for position +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl](../) - mysqlctl initializes and controls mysqld with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_reinit_config.md b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_reinit_config.md new file mode 100644 index 000000000..4a93e7e92 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_reinit_config.md @@ -0,0 +1,116 @@ +--- +title: reinit config +series: mysqlctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## mysqlctl reinit_config + +Reinitializes my.cnf file with new server_id. + +### Synopsis + +Regenerate new configuration files for an existing `mysqld` instance (generating new server_id and server_uuid values). +This could be helpful to revert configuration changes, or to pick up changes made to the bundled config in newer Vitess versions. + +``` +mysqlctl reinit_config [flags] +``` + +### Examples + +``` +mysqlctl \ + --alsologtostderr \ + --tablet_uid 101 \ + --mysql_port 12345 \ + reinit_config +``` + +### Options + +``` + -h, --help help for reinit_config +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl](../) - mysqlctl initializes and controls mysqld with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_shutdown.md b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_shutdown.md new file mode 100644 index 000000000..8443d360d --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_shutdown.md @@ -0,0 +1,114 @@ +--- +title: shutdown +series: mysqlctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## mysqlctl shutdown + +Shuts down mysqld, without removing any files. + +### Synopsis + +Stop a `mysqld` instance that was previously started with `init` or `start`. + +For large `mysqld` instances, you may need to extend the `wait_time` to shutdown cleanly. + +``` +mysqlctl shutdown [flags] +``` + +### Examples + +``` +mysqlctl --tablet_uid 101 --alsologtostderr shutdown +``` + +### Options + +``` + -h, --help help for shutdown + --wait_time duration How long to wait for mysqld shutdown. (default 5m0s) +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl](../) - mysqlctl initializes and controls mysqld with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_start.md b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_start.md new file mode 100644 index 000000000..88536adf3 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_start.md @@ -0,0 +1,113 @@ +--- +title: start +series: mysqlctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## mysqlctl start + +Starts mysqld on an already 'init'-ed directory. + +### Synopsis + +Resume an existing `mysqld` instance that was previously bootstrapped with `init` or `init_config` + +``` +mysqlctl start [flags] +``` + +### Examples + +``` +mysqlctl --tablet_uid 101 --alsologtostderr start +``` + +### Options + +``` + -h, --help help for start + --mysqld_args strings List of comma-separated flags to pass additionally to mysqld. + --wait_time duration How long to wait for mysqld startup. (default 5m0s) +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl](../) - mysqlctl initializes and controls mysqld with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_teardown.md b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_teardown.md new file mode 100644 index 000000000..7aa9d8093 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctl/mysqlctl_teardown.md @@ -0,0 +1,117 @@ +--- +title: teardown +series: mysqlctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## mysqlctl teardown + +Shuts mysqld down and removes the directory. + +### Synopsis + +{{< warning >}} +This is a destructive operation. +{{}} + +Shuts down a `mysqld` instance and removes its data directory. + +``` +mysqlctl teardown [flags] +``` + +### Examples + +``` +mysqlctl --tablet_uid 101 --alsologtostderr teardown +``` + +### Options + +``` + -f, --force Remove the root directory even if mysqld shutdown fails. + -h, --help help for teardown + --wait_time duration How long to wait for mysqld shutdown. (default 5m0s) +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port. (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file. + --mysqlctl_client_protocol string the protocol to use to talk to the mysqlctl server (default "grpc") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID. (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + +### SEE ALSO + +* [mysqlctl](../) - mysqlctl initializes and controls mysqld with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/mysqlctld/_index.md b/content/en/docs/19.0/reference/programs/mysqlctld/_index.md new file mode 100644 index 000000000..b978ea7d5 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/mysqlctld/_index.md @@ -0,0 +1,138 @@ +--- +title: mysqlctld +series: mysqlctld +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## mysqlctld + +mysqlctld is a daemon that starts or initializes mysqld. + +### Synopsis + +`mysqlctld` is a gRPC server that can be used instead of the `mysqlctl` client tool. +If the target directories are empty when it is invoked, it automatically performs initialization operations to bootstrap the `mysqld` instance before starting it. +The `mysqlctld` process can subsequently receive gRPC commands from a `vttablet` to perform housekeeping operations like shutting down and restarting the `mysqld` instance as needed. + +{{< warning >}} +`mysqld_safe` is not used so the `mysqld` process will not be automatically restarted in case of a failure. +{{}} + +To enable communication with a `vttablet`, the server must be configured to receive gRPC messages on a unix domain socket. + +``` +mysqlctld [flags] +``` + +### Examples + +``` +mysqlctld \ + --log_dir=${VTDATAROOT}/logs \ + --tablet_uid=100 \ + --mysql_port=17100 \ + --socket_file=/path/to/socket_file +``` + +### Options + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --grpc_auth_mode string Which auth plugin implementation to use (eg: static) + --grpc_auth_mtls_allowed_substrings string List of substrings of at least one of the client certificate names (separated by colon). + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_auth_static_password_file string JSON File to read the users/passwords from. + --grpc_ca string server CA to use for gRPC connections, requires TLS, and enforces client certificate check + --grpc_cert string server certificate to use for gRPC connections, requires grpc_key, enables TLS + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_crl string path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake + --grpc_enable_optional_tls enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_key string server private key to use for gRPC connections, requires grpc_cert, enables TLS + --grpc_max_connection_age duration Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) + --grpc_max_connection_age_grace duration Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) + --grpc_port int Port to listen on for gRPC calls. If zero, do not listen. + --grpc_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --grpc_server_initial_conn_window_size int gRPC server initial connection window size + --grpc_server_initial_window_size int gRPC server initial window size + --grpc_server_keepalive_enforcement_policy_min_time duration gRPC server minimum keepalive time (default 10s) + --grpc_server_keepalive_enforcement_policy_permit_without_stream gRPC server permit client keepalive pings even when there are no active streams (RPCs) + -h, --help help for mysqlctld + --init_db_sql_file string Path to .sql file to run after mysqld initialization + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_port int MySQL port (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string Path to the mysqld socket file + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --port int port for the server + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --socket_file string Local unix socket file to listen on + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_uid uint32 Tablet UID (default 41983) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --wait_time duration How long to wait for mysqld startup or shutdown (default 5m0s) +``` + diff --git a/content/en/docs/19.0/reference/programs/regular-expression.txt b/content/en/docs/19.0/reference/programs/regular-expression.txt new file mode 100644 index 000000000..92dd1960c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/regular-expression.txt @@ -0,0 +1,11 @@ +Format Options: + + +Find: \n ([^ ]+) ?(.+)?\n \t(.+) +Replace: | \1 | \2 | \3 |\n + + +Format vtctl table: + +Find: ([a-z]+)(.+) +Replace: | [\1](../vtctl/serving-graph#\1) | `\1 \2` | \ No newline at end of file diff --git a/content/en/docs/19.0/reference/programs/topo2topo/_index.md b/content/en/docs/19.0/reference/programs/topo2topo/_index.md new file mode 100644 index 000000000..52630cae8 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/topo2topo/_index.md @@ -0,0 +1,60 @@ +--- +title: topo2topo +series: topo2topo +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## topo2topo + +topo2topo copies Vitess topology data from one topo server to another. + +### Synopsis + +topo2topo copies Vitess topology data from one topo server to another. +It can also be used to compare data between two topologies. + +``` +topo2topo [flags] +``` + +### Options + +``` + --alsologtostderr log to standard error as well as files + --compare compares data between topologies + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --do-keyspaces copies the keyspace information + --do-routing-rules copies the routing rules + --do-shard-replications copies the shard replication information + --do-shards copies the shard information + --do-tablets copies the tablet information + --from_implementation string topology implementation to copy data from + --from_root string topology server root to copy data from + --from_server string topology server address to copy data from + --grpc_enable_tracing Enable gRPC tracing. + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_prometheus Enable gRPC monitoring with Prometheus. + -h, --help help for topo2topo + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --to_implementation string topology implementation to copy data to + --to_root string topology server root to copy data to + --to_server string topology server address to copy data to + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + diff --git a/content/en/docs/19.0/reference/programs/vtaclcheck/_index.md b/content/en/docs/19.0/reference/programs/vtaclcheck/_index.md new file mode 100644 index 000000000..18163a29d --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtaclcheck/_index.md @@ -0,0 +1,42 @@ +--- +title: vtaclcheck +series: vtaclcheck +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtaclcheck + +vtaclcheck checks that the access-control list (ACL) rules in a given file are valid. + +``` +vtaclcheck [flags] +``` + +### Options + +``` + --acl-file string The path of the JSON ACL file to check + --alsologtostderr log to standard error as well as files + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + -h, --help help for vtaclcheck + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --static-auth-file string The path of the auth_server_static JSON file to check + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + diff --git a/content/en/docs/19.0/reference/programs/vtadmin-web.md b/content/en/docs/19.0/reference/programs/vtadmin-web.md new file mode 100644 index 000000000..7c589d953 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtadmin-web.md @@ -0,0 +1,36 @@ +--- +title: vtadmin-web +--- + +## Environment Variables + +These environment variables configure VTAdmin, most commonly when creating a `vtadmin-web` production build as described in the [VTAdmin Operator's Guide][operators_guide]. These environment variables also enumerated in [web/vtadmin/vite-env.d.ts][vtadmin_env_ref]. + +Under the hood, `vtadmin-web` uses [vite][vite], which requires all environment variables to be prefixed with `VITE` to avoid accidentally including secrets in the static build. For more on custom environment variables with vite, see ["Env Variables and Modes"][vite_env_ref]. + +These environment variables can be passed inline to the `npm run build` command or [added to a .env file][vite_env_file_ref]. + + +| Name | Required | Type | Default | Definition | +| -------- | --------- | --------- | --------- |--------- | +| `VITE_VTADMIN_API_ADDRESS` | **Required** | string | - | The full address of vtadmin-api's HTTP(S) interface. Example: "https://vtadmin.example.com:12345" | +| `VITE_BUGSNAG_API_KEY` | Optional | string | - | An API key for https://bugsnag.com. If defined, the @bugsnag/js client will be initialized. Your Bugsnag API key can be found in your Bugsnag Project Settings. | +| `VITE_BUILD_BRANCH` | Optional | string | - | The branch vtadmin-web was built with. Used only for debugging; will appear on the (secret) /settings route in the UI. | +| `VITE_BUILD_SHA` | Optional | string | - | The SHA vtadmin-web was built with. Used only for debugging; will appear on the (secret) /settings route in the UI. | +| `VITE_DOCUMENT_TITLE` | Optional | string | "VTAdmin" | Used for the document.title property. Overriding this can be useful to differentiate between multiple VTAdmin deployments, e.g., "VTAdmin (staging)". | +| `VITE_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS` | Optional | string | - | Optional, but recommended. When `"true"`, enables front-end components that query vtadmin-api's /api/experimental/tablet/{tablet}/debug/vars endpoint. | +| `VITE_FETCH_CREDENTIALS` | Optional | string | - | Configures the `credentials` property for fetch requests made against vtadmin-api. If unspecified, uses fetch defaults. See https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#sending_a_request_with_credentials_included | +| `VITE_READONLY_MODE` | Optional | string | "false" | If "true", UI controls that correspond to write actions (PUT, POST, DELETE) will be hidden. Note that this *only* affects the UI. If write actions are a concern, Vitess operators are encouraged to also [configure vtadmin-api for role-based access control (RBAC)][rbac] if needed. | + +[vite]: https://vitejs.dev/ +[vite_env_ref]: https://vitejs.dev/guide/env-and-mode.html +[vite_env_file_ref]: https://vitejs.dev/guide/env-and-mode.html#env-files#adding-development-environment-variables-in-env +[operators_guide]: ../../vtadmin/operators_guide +[rbac]: ../../vtadmin/role-based-access-control +[vtadmin_env_ref]: https://github.com/vitessio/vitess/blob/main/web/vtadmin/vite-env.d.ts + +These environment variables are automatically [filled in by vite](https://vitejs.dev/guide/env-and-mode.html#env-variables) and you do not have to provide them. They are available in the `import.meta.env` object at run time, and listed here for full coverage of environment variables: + +| Name | Type | Default | Definition | +| -------- | --------- | --------- | --------- | +| `MODE` | string | "production", "staging", or "development" | The current mode in which vite is running | diff --git a/content/en/docs/19.0/reference/programs/vtadmin.md b/content/en/docs/19.0/reference/programs/vtadmin.md new file mode 100644 index 000000000..a86a46084 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtadmin.md @@ -0,0 +1,80 @@ +--- +title: vtadmin +--- + +## Flags + +These flags are provided to the `vtadmin` process. They are also referenced in [cmd/vtadmin/main.go](https://github.com/vitessio/vitess/blob/main/go/cmd/vtadmin/main.go). + +### Common flags + +| Name | Required | Type | Default | Definition | +| -------- | --------- | --------- | --------- |--------- | +| `addr` | **Required** | string | ":15000" | The address for `vtadmin` to serve on. | +| `lame-duck-duration` | Optional | [time.Duration][duration] | "5s" | The length of the lame duck period at shutdown. | +| `lmux-read-timeout` | Optional | [time.Duration][duration] | "1s" | How long to spend connection muxing. | + +[duration]: https://pkg.go.dev/time#ParseDuration + +### Cluster config flags + +One of `cluster`, `cluster-defaults`, or `cluster-config` file is required. Multiple configurations are permitted; precedence is noted below. + +| Name | Definition | +| -------- | --------- | +| `cluster` | Per-cluster configuration. Any values here take precedence over those defined by the `cluster-defaults` and/or `cluster-config` flags. | +| `cluster-config` | Path to a yaml cluster configuration; for reference, see the example [clusters.yaml](https://github.com/vitessio/vitess/blob/main/doc/vtadmin/clusters.yaml). | +| `cluster-defaults` | Default options for all clusters. | +| `enable-dynamic-clusters` | Defaults to `false`. Whether to enable dynamic clusters that are set by request header cookies or gRPC metadata. | + +### Tracing flags + +| Name | Required | Type | Default | Definition | +| -------- | --------- | --------- | --------- |--------- | +| `grpc-tracing` | Optional | boolean | `false` | If true, enables tracing on the gRPC server. | +| `http-tracing` | Optional | boolean | `false` | If true, enables tracing on the HTTP server. | +| `tracer` | Optional | string | "noop" | Which tracing service to use; see [go/trace/trace.go](https://github.com/vitessio/vitess/blob/main/go/trace/trace.go). | +| `tracing-enable-logging` | Optional | boolean | `false` | Whether to enable logging in the tracing service; see [go/trace/trace.go](https://github.com/vitessio/vitess/blob/main/go/trace/trace.go). | +| `tracing-sampling-type` | Optional | string | - | Sampling strategy to use for jaeger. Possible values are "const", "probabilistic", "rateLimiting", or "remote"; see [go/trace/plugin_jaeger.go](https://github.com/vitessio/vitess/blob/main/go/trace/plugin_jaeger.go). | +| `tracing-sampling-rate` | Optional | float | 0.1 | Sampling rate for the probabilistic jaeger sampler; see [go/trace/plugin_jaeger.go](https://github.com/vitessio/vitess/blob/main/go/trace/plugin_jaeger.go). | +### gRPC server flags + +| Name | Required | Type | Default | Definition | +| -------- | --------- | --------- | --------- |--------- | +| `grpc-allow-reflection` | Optional | boolean | `false` | Whether to register the gRPC server for reflection; this is required to use tools like `grpc_cli`. +| `grpc-enable-channelz` | Optional | boolean | `false` | Whether to enable the [channelz](https://grpc.io/blog/a-short-introduction-to-channelz/) service on the gRPC server. | + +### HTTP server flags + +| Name | Required | Type | Default | Definition | +| -------- | --------- | --------- | --------- |--------- | +| `http-origin` | **Required** | string | - | repeated, comma-separated flag of allowed CORS origins. omit to disable CORS | +| `http-metrics-endpoint` | **Recommended** | string | "/metrics" | HTTP endpoint to expose prometheus metrics on. Omit to disable scraping metrics. Using a path used by VTAdmin's http API is unsupported and causes undefined behavior.| +| `http-tablet-url-tmpl` | **Recommended** | string | "https://{{ .Tablet.Hostname }}:80" | Go template string to generate a reachable http(s) address for a tablet. Currently used to make passthrough requests to /debug/vars endpoints. Example: `"https://{{ .Tablet.Hostname }}:80"` | +| `http-debug-omit-env` | Optional | boolean | `false` | The name of an environment variable to omit from /debug/env, if http debug endpoints are enabled. Specify multiple times to omit multiple env vars. | +| `http-debug-sanitize-env`| Optional | string | - | The name of an environment variable to sanitize in /debug/env, if http debug endpoints are enabled. Specify multiple times to sanitize multiple env vars. | +| `http-no-compress` | Optional | boolean | `false` | Whether to disable compression of HTTP API responses. | +| `http-no-debug` | Optional | boolean | `false` | Whether to disable `/debug/pprof/*` and `/debug/env` HTTP endpoints | + + +### RBAC flags + +If using RBAC, both the `--rbac` and `--rbac-config` flags must be set. If not using RBAC, the `--no-rbac` must be set. + +| Name | Required | Type | Default | Definition | +| -------- | --------- | --------- | --------- |--------- | +| `no-rbac` | Optional | boolean | `false` | Whether to disable RBAC. | +| `rbac` | Optional | boolean | `false` | Whether to enable RBAC. | +| `rbac-config` | Optional | string | - | Path to an RBAC config file. Must be set if passing `--rbac`. | + +### glog flags + +See https://pkg.go.dev/github.com/golang/glog. + +| Name | Required | Type | Default | Definition | +| -------- | --------- | --------- | --------- |--------- | +| `logtostderr` | Optional | boolean | `false` | If true, logs are written to standard error instead of to files. +| `alsologtostderr` | Optional | boolean | `false` | If true, logs are written to standard error as well as to files. +| `stderrthreshold` | Optional | string | `ERROR` | Log events at or above this severity are logged to standard error as well as to files. +| `log_dir` | Optional | string | - | Log files will be written to this directory instead of the default temporary directory. | +| `v` | Optional | int | 0 | Enable V-leveled logging at the specified level. | diff --git a/content/en/docs/19.0/reference/programs/vtbackup.md b/content/en/docs/19.0/reference/programs/vtbackup.md new file mode 100644 index 000000000..1ee065c41 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtbackup.md @@ -0,0 +1,239 @@ +--- +title: vtbackup +description: The Vitess Batch Command for Backup Maintenance +--- + +`vtbackup` is a batch comand to perform a single pass of backup maintenance for a shard. + +When run periodically for each shard, `vtbackup` can ensure these configurable policies: + - There is always a recent backup for the shard. + - Old backups for the shard are removed. + +Whatever system launches `vtbackup` is responsible for the following: + - Running `vtbackup` with similar flags that would be used for a vttablet and + mysqlctld in the target shard to be backed up. + - Provisioning as much disk space for `vtbackup` as would be given to vttablet. + The data directory MUST be empty at startup. Do NOT reuse a persistent disk. + - Running `vtbackup` periodically for each shard, for each backup storage location. + - Ensuring that at most one instance runs at a time for a given pair of shard + and backup storage location. + - Retrying `vtbackup` if it fails. + - Alerting human operators if the failure is persistent. + +## Example Usage + +On a running Vitess cluster, the following command will create a backup using `vtbackup` for keyspace `commerce` and shard `0`. + +```bash +export TOPOLOGY_FLAGS="--topo_implementation etcd2 --topo_global_server_address localhost:2379 --topo_global_root /vitess/global" +export VTROOT="/tmp" + +mkdir -p $VTROOT/{backups,socket} + +vtbackup \ + $TOPOLOGY_FLAGS \ + --backup_storage_implementation file \ + --file_backup_storage_root $VTROOT/backups/vitess-local/ \ + --logtostderr=true \ + --mysql_socket $VTROOT/socket/mysql.sock \ + --port 15500 \ + --mysql_port 33306 \ + --init_shard=0 \ + --init_keyspace=commerce \ + --db_dba_user=vt_dba +``` + +While it is running, `vtbackup` serves debugging info and metrics on port `15500`, and starts a mysqld daemon serving on port `33306`. + +## Options + +| Name | Type | Definition | +| :------------------------------------ | :--------- | :----------------------------------------------------------------------------------------- | +| --allow_first_backup | boolean | Allow this job to take the first backup of an existing shard. | +| --alsologtostderr | boolean | log to standard error as well as files | +| --azblob_backup_account_key_file | string | Path to a file containing the Azure Storage account key; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_KEY will be used as the key itself (NOT a file path). | +| --azblob_backup_account_name | string | Azure Storage Account name for backups; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_NAME will be used. | +| --azblob_backup_buffer_size | int | The memory buffer size to use in bytes, per file or stripe, when streaming to Azure Blob Service. (default 104857600) | +| --azblob_backup_container_name | string | Azure Blob Container Name. | +| --azblob_backup_parallelism | int | Azure Blob operation parallelism (requires extra memory when increased -- a multiple of azblob_backup_buffer_size). (default 1) | +| --azblob_backup_storage_root | string | Root prefix for all backup-related Azure Blobs; this should exclude both initial and trailing '/' (e.g. just 'a/b' not '/a/b/'). | +| --backup_engine_implementation | string | Specifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin") | +| --backup_storage_block_size | int | if backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000) | +| --backup_storage_compress | boolean | if set, the backup files will be compressed. (default true) | +| --backup_storage_implementation | string | Which backup storage implementation to use for creating and restoring backups. | +| --backup_storage_number_blocks | int | if backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, at once, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression. (default 2) | +| --builtinbackup-file-read-buffer-size | uint | read files using an IO buffer of this many bytes. Golang defaults are used when set to 0. | +| --builtinbackup-file-write-buffer-size | uint | write files using an IO buffer of this many bytes. Golang defaults are used when set to 0. (default 2097152) | +| --builtinbackup_mysqld_timeout | duration | how long to wait for mysqld to shutdown at the start of the backup. (default 10m0s) | +| --builtinbackup_progress | duration | how often to send progress updates when backing up large files. (default 5s) | +| --ceph_backup_storage_config | string | Path to JSON config file for ceph backup storage. (default "ceph_backup_config.json") | +| --compression-engine-name | string | compressor engine used for compression. (default "pargzip") | +| --compression-level | int | what level to pass to the compressor. (default 1) | +| --concurrency | int | (init restore parameter) how many concurrent files to restore at once (default 4) | +| --consul_auth_static_file | string | JSON File to read the topos/tokens from. | +| --db-credentials-file | string | db credentials file; send SIGHUP to reload this file | +| --db-credentials-server | string | db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") | +| --db-credentials-vault-addr | string | URL to Vault server | +| --db-credentials-vault-path | string | Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds | +| --db-credentials-vault-role-mountpoint | string | Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") | +| --db-credentials-vault-role-secretidfile | string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable | +| --db-credentials-vault-roleid | string | Vault AppRole id; can also be passed using VAULT_ROLEID environment variable | +| --db-credentials-vault-timeout | duration | Timeout for vault API operations (default 10s) | +| --db-credentials-vault-tls-ca | string | Path to CA PEM for validating Vault server certificate | +| --db-credentials-vault-tokenfile | string | Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable | +| --db-credentials-vault-ttl | duration | How long to cache DB credentials from the Vault server (default 30m0s) | +| --db_allprivs_password | string | db allprivs password | +| --db_allprivs_use_ssl | boolean | Set this flag to false to make the allprivs connection to not use ssl (default true) | +| --db_allprivs_user | string | db allprivs user userKey (default "vt_allprivs") | +| --db_app_password | string | db app password | +| --db_app_use_ssl | boolean | Set this flag to false to make the app connection to not use ssl (default true) | +| --db_app_user | string | db app user userKey (default "vt_app") | +| --db_appdebug_password | string | db appdebug password | +| --db_appdebug_use_ssl | boolean | Set this flag to false to make the appdebug connection to not use ssl (default true) | +| --db_appdebug_user | string | db appdebug user userKey (default "vt_appdebug") | +| --db_charset | string | Character set used for this tablet. (default "utf8mb4") | +| --db_conn_query_info | boolean | enable parsing and processing of QUERY_OK info fields | +| --db_connect_timeout_ms | int | connection timeout to mysqld in milliseconds (0 for no timeout) | +| --db_dba_password | string | db dba password | +| --db_dba_use_ssl | boolean | Set this flag to false to make the dba connection to not use ssl (default true) | +| --db_dba_user | string | db dba user userKey (default "vt_dba") | +| --db_erepl_password | string | db erepl password | +| --db_erepl_use_ssl | boolean | Set this flag to false to make the erepl connection to not use ssl (default true) | +| --db_erepl_user | string | db erepl user userKey (default "vt_erepl") | +| --db_filtered_password | string | db filtered password | +| --db_filtered_use_ssl | boolean | Set this flag to false to make the filtered connection to not use ssl (default true) | +| --db_filtered_user | string | db filtered user userKey (default "vt_filtered") | +| --db_flags | uint | Flag values as defined by MySQL. | +| --db_flavor | string | Flavor overrid. Valid value is FilePos. | +| --db_host | string | The host name for the tcp connection. | +| --db_port | int | tcp port | +| --db_repl_password | string | db repl password | +| --db_repl_use_ssl | boolean | Set this flag to false to make the repl connection to not use ssl (default true) | +| --db_repl_user | string | db repl user userKey (default "vt_repl") | +| --db_server_name | string | server name of the DB we are connecting to. | +| --db_socket | string | The unix socket to connect on. If this is specified, host and port will not be used. | +| --db_ssl_ca | string | connection ssl ca | +| --db_ssl_ca_path | string | connection ssl ca path | +| --db_ssl_cert | string | connection ssl certificate | +| --db_ssl_key | string | connection ssl key | +| --db_ssl_mode | SslMode | SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. | +| --db_tls_min_version | string | Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. | +| --detach | boolean | detached mode - run backups detached from the terminal | +| --disable-redo-log | boolean | Disable InnoDB redo log during replication-from-primary phase of backup. | +| --emit_stats | boolean | If set, emit stats to push-based monitoring and stats backends | +| --external-compressor | string | command with arguments to use when compressing a backup. | +| --external-compressor-extension | string | extension to use when using an external compressor. | +| --external-decompressor | string | command with arguments to use when decompressing a backup. | +| --file_backup_storage_root | string | Root directory for the file backup storage. | +| --gcs_backup_storage_bucket | string | Google Cloud Storage bucket to use for backups. | +| --gcs_backup_storage_root | string | Root prefix for all backup-related object names. | +| --grpc_auth_static_client_creds | string | When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. | +| --grpc_compression | string | Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy | +| --grpc_enable_tracing | boolean | Enable gRPC tracing. | +| --grpc_initial_conn_window_size | int | gRPC initial connection window size | +| --grpc_initial_window_size | int | gRPC initial window size | +| --grpc_keepalive_time | duration | After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) | +| --grpc_keepalive_timeout | duration | After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) | +| --grpc_max_message_size | int | Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) | +| --grpc_prometheus | boolean | Enable gRPC monitoring with Prometheus. | +| --incremental_from_pos | string | Position of previous backup. Default: empty. If given, then this backup becomes an incremental backup from given position. If value is 'auto', backup taken from last successful backup position | +| --init_db_name_override | string | (init parameter) override the name of the db used by vttablet | +| --init_db_sql_file | string | path to .sql file to run after mysql_install_db | +| --init_keyspace | string | (init parameter) keyspace to use for this tablet | +| --init_shard | string | (init parameter) shard to use for this tablet | +| --initial_backup | boolean | Instead of restoring from backup, initialize an empty database with the provided init_db_sql_file and upload a backup of that for the shard, if the shard has no backups yet. This can be used to seed a brand new shard with an initial, empty backup. If any backups already exist for the shard, this will be considered a successful no-op. This can only be done before the shard exists in topology (i.e. before any tablets are deployed). | +| --keep-alive-timeout | duration | Wait until timeout elapses after a successful backup before shutting down. | +| --keep_logs | boolean | keep logs for this long (using ctime) (zero to keep forever) | +| --keep_logs_by_mtime | duration | keep logs for this long (using mtime) (zero to keep forever) | +| --lock-timeout | duration | Maximum time for which a shard/keyspace lock can be acquired for (default 45s) | +| --log_backtrace_at | traceLocation | when logging hits line file:N, emit a stack trace (default :0) | +| --log_dir | string | If non-empty, write log files in this directory | +| --log_err_stacks | boolean | log stack traces for errors | +| --log_rotate_max_size | uint | size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) | +| --logtostderr | boolean | log to standard error instead of files | +| --manifest-external-decompressor | string | command with arguments to store in the backup manifest when compressing a backup with an external compression engine. | +| --min_backup_interval | duration | Only take a new backup if it's been at least this long since the most recent backup. | +| --min_retention_count | int | Always keep at least this many of the most recent backups in this backup storage location, even if some are older than the min_retention_time. This must be at least 1 since a backup must always exist to allow new backups to be made (default 1) | +| --min_retention_time | duration | Keep each old backup for at least this long before removing it. Set to 0 to disable pruning of old backups. | +| --mycnf-file | string | path to my.cnf, if reading all config params from there | +| --mycnf_bin_log_path | string | mysql binlog path | +| --mycnf_data_dir | string | data directory for mysql | +| --mycnf_error_log_path | string | mysql error log path | +| --mycnf_general_log_path | string | mysql general log path | +| --mycnf_innodb_data_home_dir | string | Innodb data home directory | +| --mycnf_innodb_log_group_home_dir | string | Innodb log group home directory | +| --mycnf_master_info_file | string | mysql master.info file | +| --mycnf_mysql_port | int | port mysql is listening on | +| --mycnf_pid_file | string | mysql pid file | +| --mycnf_relay_log_index_path | string | mysql relay log index path | +| --mycnf_relay_log_info_path | string | mysql relay log info path | +| --mycnf_relay_log_path | string | mysql relay log path | +| --mycnf_secure_file_priv | string | mysql path for loading secure files | +| --mycnf_server_id | int | mysql server id of the server (if specified, mycnf-file will be ignored) | +| --mycnf_slow_log_path | string | mysql slow query log path | +| --mycnf_socket_file | string | mysql socket file | +| --mycnf_tmp_dir | string | mysql tmp directory | +| --mysql_port | int | mysql port (default 3306) | +| --mysql_server_version | string | MySQL server version to advertise. | +| --mysql_socket | string | path to the mysql socket | +| --mysql_timeout | duration | how long to wait for mysqld startup (default 5m0s) | +| --port | int | port for the server | +| --pprof | strings | enable profiling | +| --purge_logs_interval | boolean | how often try to remove old logs (default 1h0m0s) | +| --remote_operation_timeout | duration | time to wait for a remote operation (default 15s) | +| --restart_before_backup | boolean | Perform a mysqld clean/full restart after applying binlogs, but before taking the backup. Only makes sense to work around xtrabackup bugs. | +| --s3_backup_aws_endpoint | string | endpoint of the S3 backend (region must be provided). | +| --s3_backup_aws_region | string | AWS region to use. (default "us-east-1") | +| --s3_backup_aws_retries | int | AWS request retries. (default -1) | +| --s3_backup_force_path_style | | force the s3 path style. | +| --s3_backup_log_level | string | determine the S3 loglevel to use from LogOff, LogDebug, LogDebugWithSigning, LogDebugWithHTTPBody, LogDebugWithRequestRetries, LogDebugWithRequestErrors. (default "LogOff") | +| --s3_backup_server_side_encryption | string | server-side encryption algorithm (e.g., AES256, aws:kms, sse_c:/path/to/key/file). | +| --s3_backup_storage_bucket | string | S3 bucket to use for backups. | +| --s3_backup_storage_root | string | root prefix for all backup-related object names. | +| --s3_backup_tls_skip_verify_cert | | skip the 'certificate is valid' check for SSL connections. | +| --security_policy | string | the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) | +| --sql-max-length-errors | int | truncate queries in error logs to the given length (default unlimited) | +| --sql-max-length-ui | int | truncate queries in debug UIs to the given length (default 512) (default 512) | +| --stats_backend | string | The name of the registered push-based monitoring/stats backend to use | +| --stats_combine_dimensions | string | List of dimensions to be combined into a single "all" value in exported stats vars | +| --stats_common_tags | strings | Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 | +| --stats_drop_variables | string | Variables to be dropped from the list of exported variables. | +| --stats_emit_period | duration | Interval between emitting stats to all registered backends (default 1m0s) | +| --stderrthreshold | severity | logs at or above this threshold go to stderr (default 1) | +| --tablet_manager_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_manager_grpc_cert | string | the cert to use to connect | +| --tablet_manager_grpc_concurrency | int | concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) | +| --tablet_manager_grpc_connpool_size | int | number of tablets to keep tmclient connections open to (default 100) | +| --tablet_manager_grpc_crl | string | the server crl to use to validate server certificates when connecting | +| --tablet_manager_grpc_key | string | the key to use to connect | +| --tablet_manager_grpc_server_name | string | the server name to use to validate server certificate | +| --tablet_manager_protocol | string | Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") | +| --topo_consul_lock_delay | duration | LockDelay for consul session. (default 15s) | +| --topo_consul_lock_session_checks | string | List of checks for consul session. (default "serfHealth") | +| --topo_consul_lock_session_ttl | string | TTL for consul session. | +| --topo_consul_watch_poll_duration | duration | time of the long poll for watch queries. (default 30s) | +| --topo_etcd_lease_ttl | int | Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) | +| --topo_etcd_tls_ca | string | path to the ca to use to validate the server cert when connecting to the etcd topo server | +| --topo_etcd_tls_cert | string | path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS | +| --topo_etcd_tls_key | string | path to the client key to use to connect to the etcd topo server, enables TLS | +| --topo_global_root | string | the path of the global topology data in the global topology server | +| --topo_global_server_address | string | the address of the global topology server | +| --topo_implementation | string | the topology implementation to use | +| --topo_zk_auth_file | string | auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass | +| --topo_zk_base_timeout | duration | zk base timeout (see zk.Connect) (default 30s) | +| --topo_zk_max_concurrency | int | maximum number of pending requests to send to a Zookeeper server. (default 64) | +| --topo_zk_tls_ca | string | the server ca to use to validate servers when connecting to the zk topo server | +| --topo_zk_tls_cert | string | the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS | +| --topo_zk_tls_key | string | the key to use to connect to the zk topo server, enables TLS | +| --upgrade-safe | boolean | Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades | +| --v | Level | log level for V logs | +| -v, --version | | print binary version | +| --vmodule | moduleSpec | comma-separated list of pattern=N settings for file-filtered logging | +| --xbstream_restore_flags | string | Flags to pass to xbstream command during restore. These should be space separated and will be added to the end of the command. These need to match the ones used for backup e.g. --compress / --decompress, --encrypt / --decrypt | +| --xtrabackup_backup_flags | string | Flags to pass to backup command. These should be space separated and will be added to the end of the command | +| --xtrabackup_prepare_flags | string | Flags to pass to prepare command. These should be space separated and will be added to the end of the command | +| --xtrabackup_root_path | string | Directory location of the xtrabackup and xbstream executables, e.g., /usr/bin | +| --xtrabackup_stream_mode | string | Which mode to use if streaming, valid values are tar and xbstream. Please note that tar is not supported in XtraBackup 8.0 (default "tar") | +| --xtrabackup_stripe_block_size | uint | Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) | +| --xtrabackup_stripes | uint | If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression | +| --xtrabackup_user | string | User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. | diff --git a/content/en/docs/19.0/reference/programs/vtbackup/_index.md b/content/en/docs/19.0/reference/programs/vtbackup/_index.md new file mode 100644 index 000000000..bfc151971 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtbackup/_index.md @@ -0,0 +1,256 @@ +--- +title: vtbackup +series: vtbackup +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtbackup + +vtbackup is a batch command to perform a single pass of backup maintenance for a shard. + +### Synopsis + +vtbackup is a batch command to perform a single pass of backup maintenance for a shard. + +When run periodically for each shard, vtbackup can ensure these configurable policies: + * There is always a recent backup for the shard. + * Old backups for the shard are removed. + +Whatever system launches vtbackup is responsible for the following: + - Running vtbackup with similar flags that would be used for a vttablet and + mysqlctld in the target shard to be backed up. + - Provisioning as much disk space for vtbackup as would be given to vttablet. + The data directory MUST be empty at startup. Do NOT reuse a persistent disk. + - Running vtbackup periodically for each shard, for each backup storage location. + - Ensuring that at most one instance runs at a time for a given pair of shard + and backup storage location. + - Retrying vtbackup if it fails. + - Alerting human operators if the failure is persistent. + +The process vtbackup follows to take a new backup has the following steps: + 1. Restore from the most recent backup. + 2. Start a mysqld instance (but no vttablet) from the restored data. + 3. Instruct mysqld to connect to the current shard primary and replicate any + transactions that are new since the last backup. + 4. Ask the primary for its current replication position and set that as the goal + for catching up on replication before taking the backup, so the goalposts + don't move. + 5. Wait until replication is caught up to the goal position or beyond. + 6. Stop mysqld and take a new backup. + +Aside from additional replication load while vtbackup's mysqld catches up on +new transactions, the shard should be otherwise unaffected. Existing tablets +will continue to serve, and no new tablets will appear in topology, meaning no +query traffic will ever be routed to vtbackup's mysqld. This silent operation +mode helps make backups minimally disruptive to serving capacity and orthogonal +to the handling of the query path. + +The command-line parameters to vtbackup specify a policy for when a new backup +is needed, and when old backups should be removed. If the existing backups +already satisfy the policy, then vtbackup will do nothing and return success +immediately. + +``` +vtbackup [flags] +``` + +### Options + +``` + --allow_first_backup Allow this job to take the first backup of an existing shard. + --alsologtostderr log to standard error as well as files + --azblob_backup_account_key_file string Path to a file containing the Azure Storage account key; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_KEY will be used as the key itself (NOT a file path). + --azblob_backup_account_name string Azure Storage Account name for backups; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_NAME will be used. + --azblob_backup_buffer_size int The memory buffer size to use in bytes, per file or stripe, when streaming to Azure Blob Service. (default 104857600) + --azblob_backup_container_name string Azure Blob Container Name. + --azblob_backup_parallelism int Azure Blob operation parallelism (requires extra memory when increased -- a multiple of azblob_backup_buffer_size). (default 1) + --azblob_backup_storage_root string Root prefix for all backup-related Azure Blobs; this should exclude both initial and trailing '/' (e.g. just 'a/b' not '/a/b/'). + --backup_engine_implementation string Specifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin") + --backup_storage_block_size int if backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000) + --backup_storage_compress if set, the backup files will be compressed. (default true) + --backup_storage_implementation string Which backup storage implementation to use for creating and restoring backups. + --backup_storage_number_blocks int if backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, in parallel, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression. (default 2) + --builtinbackup-file-read-buffer-size uint read files using an IO buffer of this many bytes. Golang defaults are used when set to 0. + --builtinbackup-file-write-buffer-size uint write files using an IO buffer of this many bytes. Golang defaults are used when set to 0. (default 2097152) + --builtinbackup_mysqld_timeout duration how long to wait for mysqld to shutdown at the start of the backup. (default 10m0s) + --builtinbackup_progress duration how often to send progress updates when backing up large files. (default 5s) + --ceph_backup_storage_config string Path to JSON config file for ceph backup storage. (default "ceph_backup_config.json") + --compression-engine-name string compressor engine used for compression. (default "pargzip") + --compression-level int what level to pass to the compressor. (default 1) + --concurrency int (init restore parameter) how many concurrent files to restore at once (default 4) + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consul_auth_static_file string JSON File to read the topos/tokens from. + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_allprivs_password string db allprivs password + --db_allprivs_use_ssl Set this flag to false to make the allprivs connection to not use ssl (default true) + --db_allprivs_user string db allprivs user userKey (default "vt_allprivs") + --db_app_password string db app password + --db_app_use_ssl Set this flag to false to make the app connection to not use ssl (default true) + --db_app_user string db app user userKey (default "vt_app") + --db_appdebug_password string db appdebug password + --db_appdebug_use_ssl Set this flag to false to make the appdebug connection to not use ssl (default true) + --db_appdebug_user string db appdebug user userKey (default "vt_appdebug") + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_erepl_password string db erepl password + --db_erepl_use_ssl Set this flag to false to make the erepl connection to not use ssl (default true) + --db_erepl_user string db erepl user userKey (default "vt_erepl") + --db_filtered_password string db filtered password + --db_filtered_use_ssl Set this flag to false to make the filtered connection to not use ssl (default true) + --db_filtered_user string db filtered user userKey (default "vt_filtered") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_repl_password string db repl password + --db_repl_use_ssl Set this flag to false to make the repl connection to not use ssl (default true) + --db_repl_user string db repl user userKey (default "vt_repl") + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --detach detached mode - run backups detached from the terminal + --disable-redo-log Disable InnoDB redo log during replication-from-primary phase of backup. + --emit_stats If set, emit stats to push-based monitoring and stats backends + --external-compressor string command with arguments to use when compressing a backup. + --external-compressor-extension string extension to use when using an external compressor. + --external-decompressor string command with arguments to use when decompressing a backup. + --file_backup_storage_root string Root directory for the file backup storage. + --gcs_backup_storage_bucket string Google Cloud Storage bucket to use for backups. + --gcs_backup_storage_root string Root prefix for all backup-related object names. + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_prometheus Enable gRPC monitoring with Prometheus. + -h, --help help for vtbackup + --incremental_from_pos string Position of previous backup. Default: empty. If given, then this backup becomes an incremental backup from given position. If value is 'auto', backup taken from last successful backup position + --init_db_name_override string (init parameter) override the name of the db used by vttablet + --init_db_sql_file string path to .sql file to run after mysql_install_db + --init_keyspace string (init parameter) keyspace to use for this tablet + --init_shard string (init parameter) shard to use for this tablet + --initial_backup Instead of restoring from backup, initialize an empty database with the provided init_db_sql_file and upload a backup of that for the shard, if the shard has no backups yet. This can be used to seed a brand new shard with an initial, empty backup. If any backups already exist for the shard, this will be considered a successful no-op. This can only be done before the shard exists in topology (i.e. before any tablets are deployed). + --keep-alive-timeout duration Wait until timeout elapses after a successful backup before shutting down. + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lock-timeout duration Maximum time for which a shard/keyspace lock can be acquired for (default 45s) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --manifest-external-decompressor string command with arguments to store in the backup manifest when compressing a backup with an external compression engine. + --min_backup_interval duration Only take a new backup if it's been at least this long since the most recent backup. + --min_retention_count int Always keep at least this many of the most recent backups in this backup storage location, even if some are older than the min_retention_time. This must be at least 1 since a backup must always exist to allow new backups to be made (default 1) + --min_retention_time duration Keep each old backup for at least this long before removing it. Set to 0 to disable pruning of old backups. + --mycnf-file string path to my.cnf, if reading all config params from there + --mycnf_bin_log_path string mysql binlog path + --mycnf_data_dir string data directory for mysql + --mycnf_error_log_path string mysql error log path + --mycnf_general_log_path string mysql general log path + --mycnf_innodb_data_home_dir string Innodb data home directory + --mycnf_innodb_log_group_home_dir string Innodb log group home directory + --mycnf_master_info_file string mysql master.info file + --mycnf_mysql_port int port mysql is listening on + --mycnf_pid_file string mysql pid file + --mycnf_relay_log_index_path string mysql relay log index path + --mycnf_relay_log_info_path string mysql relay log info path + --mycnf_relay_log_path string mysql relay log path + --mycnf_secure_file_priv string mysql path for loading secure files + --mycnf_server_id int mysql server id of the server (if specified, mycnf-file will be ignored) + --mycnf_slow_log_path string mysql slow query log path + --mycnf_socket_file string mysql socket file + --mycnf_tmp_dir string mysql tmp directory + --mysql_port int mysql port (default 3306) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_socket string path to the mysql socket + --mysql_timeout duration how long to wait for mysqld startup (default 5m0s) + --opentsdb_uri string URI of opentsdb /api/put method + --port int port for the server + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --remote_operation_timeout duration time to wait for a remote operation (default 15s) + --restart_before_backup Perform a mysqld clean/full restart after applying binlogs, but before taking the backup. Only makes sense to work around xtrabackup bugs. + --s3_backup_aws_endpoint string endpoint of the S3 backend (region must be provided). + --s3_backup_aws_region string AWS region to use. (default "us-east-1") + --s3_backup_aws_retries int AWS request retries. (default -1) + --s3_backup_force_path_style force the s3 path style. + --s3_backup_log_level string determine the S3 loglevel to use from LogOff, LogDebug, LogDebugWithSigning, LogDebugWithHTTPBody, LogDebugWithRequestRetries, LogDebugWithRequestErrors. (default "LogOff") + --s3_backup_server_side_encryption string server-side encryption algorithm (e.g., AES256, aws:kms, sse_c:/path/to/key/file). + --s3_backup_storage_bucket string S3 bucket to use for backups. + --s3_backup_storage_root string root prefix for all backup-related object names. + --s3_backup_tls_skip_verify_cert skip the 'certificate is valid' check for SSL connections. + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --sql-max-length-errors int truncate queries in error logs to the given length (default unlimited) + --sql-max-length-ui int truncate queries in debug UIs to the given length (default 512) (default 512) + --stats_backend string The name of the registered push-based monitoring/stats backend to use + --stats_combine_dimensions string List of dimensions to be combined into a single "all" value in exported stats vars + --stats_common_tags strings Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 + --stats_drop_variables string Variables to be dropped from the list of exported variables. + --stats_emit_period duration Interval between emitting stats to all registered backends (default 1m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --tablet_manager_grpc_ca string the server ca to use to validate servers when connecting + --tablet_manager_grpc_cert string the cert to use to connect + --tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) + --tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100) + --tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_manager_grpc_key string the key to use to connect + --tablet_manager_grpc_server_name string the server name to use to validate server certificate + --tablet_manager_protocol string Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) + --topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server + --topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS + --topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS + --topo_global_root string the path of the global topology data in the global topology server + --topo_global_server_address string the address of the global topology server + --topo_implementation string the topology implementation to use + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --upgrade-safe Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades. + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --xbstream_restore_flags string Flags to pass to xbstream command during restore. These should be space separated and will be added to the end of the command. These need to match the ones used for backup e.g. --compress / --decompress, --encrypt / --decrypt + --xtrabackup_backup_flags string Flags to pass to backup command. These should be space separated and will be added to the end of the command + --xtrabackup_prepare_flags string Flags to pass to prepare command. These should be space separated and will be added to the end of the command + --xtrabackup_root_path string Directory location of the xtrabackup and xbstream executables, e.g., /usr/bin + --xtrabackup_stream_mode string Which mode to use if streaming, valid values are tar and xbstream. Please note that tar is not supported in XtraBackup 8.0 (default "tar") + --xtrabackup_stripe_block_size uint Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) + --xtrabackup_stripes uint If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression + --xtrabackup_user string User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. +``` + diff --git a/content/en/docs/19.0/reference/programs/vtclient/_index.md b/content/en/docs/19.0/reference/programs/vtclient/_index.md new file mode 100644 index 000000000..a120442cf --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtclient/_index.md @@ -0,0 +1,71 @@ +--- +title: vtclient +series: vtclient +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtclient + +vtclient connects to a vtgate server using the standard go driver API. + +### Synopsis + +vtclient connects to a vtgate server using the standard go driver API. + +For query bound variables, we assume place-holders in the query string +in the form of :v1, :v2, etc. + +``` +vtclient [flags] +``` + +### Examples + +``` +vtclient --server vtgate:15991 "SELECT * FROM messages" + +vtclient --server vtgate:15991 --target '@primary' --bind_variables '[ 12345, 1, "msg 12345" ]' "INSERT INTO messages (page,time_created_ns,message) VALUES (:v1, :v2, :v3)" +``` + +### Options + +``` + --alsologtostderr log to standard error as well as files + --bind_variables float bind variables as a json list (default null) + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --count int DMLs only: Number of times each thread executes the query. Useful for simple, sustained load testing. (default 1) + --grpc_enable_tracing Enable gRPC tracing. + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_prometheus Enable gRPC monitoring with Prometheus. + -h, --help help for vtclient + --json Output JSON instead of human-readable table + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max_sequence_id int max sequence ID. + --min_sequence_id int min sequence ID to generate. When max_sequence_id > min_sequence_id, for each query, a number is generated in [min_sequence_id, max_sequence_id) and attached to the end of the bind variables. + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --parallel int DMLs only: Number of threads executing the same query in parallel. Useful for simple load testing. (default 1) + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --qps int queries per second to throttle each thread at. + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --server string vtgate server to connect to + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --streaming use a streaming query + --target string keyspace:shard@tablet_type + --timeout duration timeout for queries (default 30s) + --use_random_sequence use random sequence for generating [min_sequence_id, max_sequence_id) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging +``` + diff --git a/content/en/docs/19.0/reference/programs/vtcombo/_index.md b/content/en/docs/19.0/reference/programs/vtcombo/_index.md new file mode 100644 index 000000000..5c05967ef --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtcombo/_index.md @@ -0,0 +1,451 @@ +--- +title: vtcombo +series: vtcombo +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtcombo + +vtcombo is a single binary containing several vitess components. + +### Synopsis + +vtcombo is a single binary containing several vitess components. + +In particular, it contains: +- A topology server based on an in-memory map. +- One vtgate instance. +- Many vttablet instances. +- A vtctld instance so it's easy to see the topology. + +``` +vtcombo [flags] +``` + +### Options + +``` + --action_timeout duration time to wait for an action before resorting to force (default 1m0s) + --allow-kill-statement Allows the execution of kill statement + --allowed_tablet_types strings Specifies the tablet types this vtgate is allowed to route queries to. Should be provided as a comma-separated set of tablet types. + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --backup_engine_implementation string Specifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin") + --backup_storage_block_size int if backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000) + --backup_storage_compress if set, the backup files will be compressed. (default true) + --backup_storage_number_blocks int if backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, in parallel, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression. (default 2) + --binlog_host string PITR restore parameter: hostname/IP of binlog server. + --binlog_password string PITR restore parameter: password of binlog server. + --binlog_player_protocol string the protocol to download binlogs from a vttablet (default "grpc") + --binlog_port int PITR restore parameter: port of binlog server. + --binlog_ssl_ca string PITR restore parameter: Filename containing TLS CA certificate to verify binlog server TLS certificate against. + --binlog_ssl_cert string PITR restore parameter: Filename containing mTLS client certificate to present to binlog server as authentication. + --binlog_ssl_key string PITR restore parameter: Filename containing mTLS client private key for use in binlog server authentication. + --binlog_ssl_server_name string PITR restore parameter: TLS server name (common name) to verify against for the binlog server we are connecting to (If not set: use the hostname or IP supplied in --binlog_host). + --binlog_user string PITR restore parameter: username of binlog server. + --buffer_drain_concurrency int Maximum number of requests retried simultaneously. More concurrency will increase the load on the PRIMARY vttablet when draining the buffer. (default 1) + --buffer_keyspace_shards string If not empty, limit buffering to these entries (comma separated). Entry format: keyspace or keyspace/shard. Requires --enable_buffer=true. + --buffer_max_failover_duration duration Stop buffering completely if a failover takes longer than this duration. (default 20s) + --buffer_min_time_between_failovers duration Minimum time between the end of a failover and the start of the next one (tracked per shard). Faster consecutive failovers will not trigger buffering. (default 1m0s) + --buffer_size int Maximum number of buffered requests in flight (across all ongoing failovers). (default 1000) + --buffer_window duration Duration for how long a request should be buffered at most. (default 10s) + --builtinbackup-file-read-buffer-size uint read files using an IO buffer of this many bytes. Golang defaults are used when set to 0. + --builtinbackup-file-write-buffer-size uint write files using an IO buffer of this many bytes. Golang defaults are used when set to 0. (default 2097152) + --builtinbackup_mysqld_timeout duration how long to wait for mysqld to shutdown at the start of the backup. (default 10m0s) + --builtinbackup_progress duration how often to send progress updates when backing up large files. (default 5s) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --cell string cell to use + --compression-engine-name string compressor engine used for compression. (default "pargzip") + --compression-level int what level to pass to the compressor. (default 1) + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consolidator-stream-query-size int Configure the stream consolidator query size in bytes. Setting to 0 disables the stream consolidator. (default 2097152) + --consolidator-stream-total-size int Configure the stream consolidator total size in bytes. Setting to 0 disables the stream consolidator. (default 134217728) + --consul_auth_static_file string JSON File to read the topos/tokens from. + --datadog-agent-host string host to send spans to. if empty, no tracing will be done + --datadog-agent-port string port to send spans to. if empty, no tracing will be done + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_allprivs_password string db allprivs password + --db_allprivs_use_ssl Set this flag to false to make the allprivs connection to not use ssl (default true) + --db_allprivs_user string db allprivs user userKey (default "vt_allprivs") + --db_app_password string db app password + --db_app_use_ssl Set this flag to false to make the app connection to not use ssl (default true) + --db_app_user string db app user userKey (default "vt_app") + --db_appdebug_password string db appdebug password + --db_appdebug_use_ssl Set this flag to false to make the appdebug connection to not use ssl (default true) + --db_appdebug_user string db appdebug user userKey (default "vt_appdebug") + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_erepl_password string db erepl password + --db_erepl_use_ssl Set this flag to false to make the erepl connection to not use ssl (default true) + --db_erepl_user string db erepl user userKey (default "vt_erepl") + --db_filtered_password string db filtered password + --db_filtered_use_ssl Set this flag to false to make the filtered connection to not use ssl (default true) + --db_filtered_user string db filtered user userKey (default "vt_filtered") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_repl_password string db repl password + --db_repl_use_ssl Set this flag to false to make the repl connection to not use ssl (default true) + --db_repl_user string db repl user userKey (default "vt_repl") + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --dbddl_plugin string controls how to handle CREATE/DROP DATABASE. use it if you are using your own database provisioning service (default "fail") + --ddl_strategy string Set default strategy for DDL statements. Override with @@ddl_strategy session variable (default "direct") + --default_tablet_type topodatapb.TabletType The default tablet type to set for queries, when one is not explicitly selected. (default PRIMARY) + --degraded_threshold duration replication lag after which a replica is considered degraded (default 30s) + --disable_active_reparents if set, do not allow active reparents. Use this to protect a cluster using external reparents. + --emit_stats If set, emit stats to push-based monitoring and stats backends + --enable-consolidator Synonym to -enable_consolidator (default true) + --enable-consolidator-replicas Synonym to -enable_consolidator_replicas + --enable-partial-keyspace-migration (Experimental) Follow shard routing rules: enable only while migrating a keyspace shard by shard. See documentation on Partial MoveTables for more. (default false) + --enable-per-workload-table-metrics If true, query counts and query error metrics include a label that identifies the workload + --enable-tx-throttler Synonym to -enable_tx_throttler + --enable-views Enable views support in vtgate. + --enable_buffer Enable buffering (stalling) of primary traffic during failovers. + --enable_buffer_dry_run Detect and log failover events, but do not actually buffer requests. + --enable_consolidator This option enables the query consolidator. (default true) + --enable_consolidator_replicas This option enables the query consolidator only on replicas. + --enable_direct_ddl Allow users to submit direct DDL statements (default true) + --enable_hot_row_protection If true, incoming transactions for the same row (range) will be queued and cannot consume all txpool slots. + --enable_hot_row_protection_dry_run If true, hot row protection is not enforced but logs if transactions would have been queued. + --enable_online_ddl Allow users to submit, review and control Online DDL (default true) + --enable_replication_reporter Use polling to track replication lag. + --enable_set_var This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections (default true) + --enable_system_settings This will enable the system settings to be changed per session at the database connection level (default true) + --enable_transaction_limit If true, limit on number of transactions open at the same time will be enforced for all users. User trying to open a new transaction after exhausting their limit will receive an error immediately, regardless of whether there are available slots or not. + --enable_transaction_limit_dry_run If true, limit on number of transactions open at the same time will be tracked for all users, but not enforced. + --enable_tx_throttler If true replication-lag-based throttling on transactions will be enabled. + --enforce_strict_trans_tables If true, vttablet requires MySQL to run with STRICT_TRANS_TABLES or STRICT_ALL_TABLES on. It is recommended to not turn this flag off. Otherwise MySQL may alter your supplied values before saving them to the database. (default true) + --external-compressor string command with arguments to use when compressing a backup. + --external-compressor-extension string extension to use when using an external compressor. + --external-decompressor string command with arguments to use when decompressing a backup. + --external_topo_server Should vtcombo use an external topology server instead of starting its own in-memory topology server. If true, vtcombo will use the flags defined in topo/server.go to open topo server + --foreign_key_mode string This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow, disallow (default "allow") + --gate_query_cache_memory int gate server query cache size in bytes, maximum amount of memory to be cached. vtgate analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 33554432) + --gc_check_interval duration Interval between garbage collection checks (default 1h0m0s) + --gc_purge_check_interval duration Interval between purge discovery checks (default 1m0s) + --gh-ost-path string override default gh-ost binary full path + --grpc-send-session-in-streaming If set, will send the session as last packet in streaming api to support transactions in streaming + --grpc-use-effective-groups If set, and SSL is not used, will set the immediate caller's security groups from the effective caller id's groups. + --grpc-use-static-authentication-callerid If set, will set the immediate caller id to the username authenticated by the static auth plugin. + --grpc_auth_mode string Which auth plugin implementation to use (eg: static) + --grpc_auth_mtls_allowed_substrings string List of substrings of at least one of the client certificate names (separated by colon). + --grpc_auth_static_password_file string JSON File to read the users/passwords from. + --grpc_ca string server CA to use for gRPC connections, requires TLS, and enforces client certificate check + --grpc_cert string server certificate to use for gRPC connections, requires grpc_key, enables TLS + --grpc_crl string path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake + --grpc_enable_optional_tls enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port + --grpc_enable_tracing Enable gRPC tracing. + --grpc_key string server private key to use for gRPC connections, requires grpc_cert, enables TLS + --grpc_max_connection_age duration Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) + --grpc_max_connection_age_grace duration Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_port int Port to listen on for gRPC calls. If zero, do not listen. + --grpc_prometheus Enable gRPC monitoring with Prometheus. + --grpc_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --grpc_server_initial_conn_window_size int gRPC server initial connection window size + --grpc_server_initial_window_size int gRPC server initial window size + --grpc_server_keepalive_enforcement_policy_min_time duration gRPC server minimum keepalive time (default 10s) + --grpc_server_keepalive_enforcement_policy_permit_without_stream gRPC server permit client keepalive pings even when there are no active streams (RPCs) + --grpc_use_effective_callerid If set, and SSL is not used, will set the immediate caller id from the effective caller id's principal. + --health_check_interval duration Interval between health checks (default 20s) + --healthcheck_retry_delay duration health check retry delay (default 2ms) + --healthcheck_timeout duration the health check timeout period (default 1m0s) + --heartbeat_enable If true, vttablet records (if master) or checks (if replica) the current time of a replication heartbeat in the sidecar database's heartbeat table. The result is used to inform the serving state of the vttablet via healthchecks. + --heartbeat_interval duration How frequently to read and write replication heartbeat. (default 1s) + --heartbeat_on_demand_duration duration If non-zero, heartbeats are only written upon consumer request, and only run for up to given duration following the request. Frequent requests can keep the heartbeat running consistently; when requests are infrequent heartbeat may completely stop between requests + -h, --help help for vtcombo + --hot_row_protection_concurrent_transactions int Number of concurrent transactions let through to the txpool/MySQL for the same hot row. Should be > 1 to have enough 'ready' transactions in MySQL and benefit from a pipelining effect. (default 5) + --hot_row_protection_max_global_queue_size int Global queue limit across all row (ranges). Useful to prevent that the queue can grow unbounded. (default 1000) + --hot_row_protection_max_queue_size int Maximum number of BeginExecute RPCs which will be queued for the same row (range). (default 20) + --init_db_name_override string (init parameter) override the name of the db used by vttablet. Without this flag, the db name defaults to vt_ + --init_keyspace string (init parameter) keyspace to use for this tablet + --init_shard string (init parameter) shard to use for this tablet + --init_tablet_type string (init parameter) the tablet type to use for this tablet. + --init_tags StringMap (init parameter) comma separated list of key:value pairs used to tag the tablet + --init_timeout duration (init parameter) timeout to use for the init phase. (default 1m0s) + --jaeger-agent-host string host and port to send spans to. if empty, no tracing will be done + --json_topo vttest.TopoData vttest proto definition of the topology, encoded in json format. See vttest.proto for more information. + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --keyspaces_to_watch strings Specifies which keyspaces this vtgate should have access to while routing queries or accessing the vschema. + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --lock-timeout duration Maximum time for which a shard/keyspace lock can be acquired for (default 45s) + --lock_heartbeat_time duration If there is lock function used. This will keep the lock connection active by using this heartbeat (default 5s) + --lock_tables_timeout duration How long to keep the table locked before timing out (default 1m0s) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_queries_to_file string Enable query logging to the specified file + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --manifest-external-decompressor string command with arguments to store in the backup manifest when compressing a backup with an external compression engine. + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --max_concurrent_online_ddl int Maximum number of online DDL changes that may run concurrently (default 256) + --max_memory_rows int Maximum number of rows that will be held in memory for intermediate results as well as the final result. (default 300000) + --max_payload_size int The threshold for query payloads in bytes. A payload greater than this threshold will result in a failure to handle the query. + --message_stream_grace_period duration the amount of time to give for a vttablet to resume if it ends a message stream, usually because of a reparent. (default 30s) + --migration_check_interval duration Interval between migration checks (default 1m0s) + --mycnf-file string path to my.cnf, if reading all config params from there + --mycnf_bin_log_path string mysql binlog path + --mycnf_data_dir string data directory for mysql + --mycnf_error_log_path string mysql error log path + --mycnf_general_log_path string mysql general log path + --mycnf_innodb_data_home_dir string Innodb data home directory + --mycnf_innodb_log_group_home_dir string Innodb log group home directory + --mycnf_master_info_file string mysql master.info file + --mycnf_mysql_port int port mysql is listening on + --mycnf_pid_file string mysql pid file + --mycnf_relay_log_index_path string mysql relay log index path + --mycnf_relay_log_info_path string mysql relay log info path + --mycnf_relay_log_path string mysql relay log path + --mycnf_secure_file_priv string mysql path for loading secure files + --mycnf_server_id int mysql server id of the server (if specified, mycnf-file will be ignored) + --mycnf_slow_log_path string mysql slow query log path + --mycnf_socket_file string mysql socket file + --mycnf_tmp_dir string mysql tmp directory + --mysql-server-keepalive-period duration TCP period between keep-alives + --mysql-server-pool-conn-read-buffers If set, the server will pool incoming connection read buffers + --mysql_allow_clear_text_without_tls If set, the server will allow the use of a clear text password over non-SSL connections. + --mysql_auth_server_impl string Which auth server implementation to use. Options: none, ldap, clientcert, static, vault. (default "static") + --mysql_default_workload string Default session workload (OLTP, OLAP, DBA) (default "OLTP") + --mysql_port int mysql port (default 3306) + --mysql_server_bind_address string Binds on this address when listening to MySQL binary protocol. Useful to restrict listening to 'localhost' only for instance. + --mysql_server_port int If set, also listen for MySQL binary protocol connections on this port. (default -1) + --mysql_server_query_timeout duration mysql query timeout + --mysql_server_read_timeout duration connection read timeout + --mysql_server_require_secure_transport Reject insecure connections but only if mysql_server_ssl_cert and mysql_server_ssl_key are provided + --mysql_server_socket_path string This option specifies the Unix socket file to use when listening for local connections. By default it will be empty and it won't listen to a unix socket + --mysql_server_ssl_ca string Path to ssl CA for mysql server plugin SSL. If specified, server will require and validate client certs. + --mysql_server_ssl_cert string Path to the ssl cert for mysql server plugin SSL + --mysql_server_ssl_crl string Path to ssl CRL for mysql server plugin SSL + --mysql_server_ssl_key string Path to ssl key for mysql server plugin SSL + --mysql_server_ssl_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --mysql_server_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_server_write_timeout duration connection write timeout + --mysql_slow_connect_warn_threshold duration Warn if it takes more than the given threshold for a mysql connection to establish + --mysql_tcp_version string Select tcp, tcp4, or tcp6 to control the socket type. (default "tcp") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --no_scatter when set to true, the planner will fail instead of producing a plan that includes scatter queries + --normalize_queries Rewrite queries with bind vars. Turn this off if the app itself sends normalized queries with bind vars. (default true) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pitr_gtid_lookup_timeout duration PITR restore parameter: timeout for fetching gtid from timestamp. (default 1m0s) + --planner-version string Sets the default planner to use when the session has not changed it. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --port int port for the server + --pprof strings enable profiling + --proto_topo vttest.TopoData vttest proto definition of the topology, encoded in compact text format. See vttest.proto for more information. + --proxy_protocol Enable HAProxy PROXY protocol on MySQL listener socket + --proxy_tablets Setting this true will make vtctld proxy the tablet status instead of redirecting to them + --pt-osc-path string override default pt-online-schema-change binary full path + --publish_retry_interval duration how long vttablet waits to retry publishing the tablet record (default 30s) + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --query-log-stream-handler string URL handler for streaming queries log (default "/debug/querylog") + --query-timeout int Sets the default query timeout (in ms). Can be overridden by session variable (query_timeout) or comment directive (QUERY_TIMEOUT_MS) + --querylog-buffer-size int Maximum number of buffered query logs before throttling log output (default 10) + --querylog-filter-tag string string that must be present in the query for it to be logged; if using a value as the tag, you need to disable query normalization + --querylog-format string format for query logs ("text" or "json") (default "text") + --querylog-row-threshold uint Number of rows a query has to return or affect before being logged; not useful for streaming queries. 0 means all queries will be logged. + --queryserver-config-acl-exempt-acl string an acl that exempt from table acl checking (this acl is free to access any vitess tables). + --queryserver-config-annotate-queries prefix queries to MySQL backend with comment indicating vtgate principal (user) and target tablet type + --queryserver-config-enable-table-acl-dry-run If this flag is enabled, tabletserver will emit monitoring metrics and let the request pass regardless of table acl check results + --queryserver-config-idle-timeout duration query server idle timeout (in seconds), vttablet manages various mysql connection pools. This config means if a connection has not been used in given idle timeout, this connection will be removed from pool. This effectively manages number of connection objects and optimize the pool performance. (default 30m0s) + --queryserver-config-max-result-size int query server max result size, maximum number of rows allowed to return from vttablet for non-streaming queries. (default 10000) + --queryserver-config-message-postpone-cap int query server message postpone cap is the maximum number of messages that can be postponed at any given time. Set this number to substantially lower than transaction cap, so that the transaction pool isn't exhausted by the message subsystem. (default 4) + --queryserver-config-olap-transaction-timeout duration query server transaction timeout (in seconds), after which a transaction in an OLAP session will be killed (default 30s) + --queryserver-config-passthrough-dmls query server pass through all dml statements without rewriting + --queryserver-config-pool-conn-max-lifetime duration query server connection max lifetime (in seconds), vttablet manages various mysql connection pools. This config means if a connection has lived at least this long, it connection will be removed from pool upon the next time it is returned to the pool. (default 0s) + --queryserver-config-pool-size int query server read pool size, connection pool is used by regular queries (non streaming, not in a transaction) (default 16) + --queryserver-config-query-cache-memory int query server query cache size in bytes, maximum amount of memory to be used for caching. vttablet analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 33554432) + --queryserver-config-query-pool-timeout duration query server query pool timeout (in seconds), it is how long vttablet waits for a connection from the query pool. If set to 0 (default) then the overall query timeout is used instead. (default 0s) + --queryserver-config-query-pool-waiter-cap int query server query pool waiter limit, this is the maximum number of queries that can be queued waiting to get a connection (default 5000) + --queryserver-config-query-timeout duration query server query timeout (in seconds), this is the query timeout in vttablet side. If a query takes more than this timeout, it will be killed. (default 30s) + --queryserver-config-schema-change-signal query server schema signal, will signal connected vtgates that schema has changed whenever this is detected. VTGates will need to have -schema_change_signal enabled for this to work (default true) + --queryserver-config-schema-reload-time duration query server schema reload time, how often vttablet reloads schemas from underlying MySQL instance in seconds. vttablet keeps table schemas in its own memory and periodically refreshes it from MySQL. This config controls the reload time. (default 30m0s) + --queryserver-config-stream-buffer-size int query server stream buffer size, the maximum number of bytes sent from vttablet for each stream call. It's recommended to keep this value in sync with vtgate's stream_buffer_size. (default 32768) + --queryserver-config-stream-pool-size int query server stream connection pool size, stream pool is used by stream queries: queries that return results to client in a streaming fashion (default 200) + --queryserver-config-stream-pool-timeout duration query server stream pool timeout (in seconds), it is how long vttablet waits for a connection from the stream pool. If set to 0 (default) then there is no timeout. (default 0s) + --queryserver-config-stream-pool-waiter-cap int query server stream pool waiter limit, this is the maximum number of streaming queries that can be queued waiting to get a connection + --queryserver-config-strict-table-acl only allow queries that pass table acl checks + --queryserver-config-terse-errors prevent bind vars from escaping in client error messages + --queryserver-config-transaction-cap int query server transaction cap is the maximum number of transactions allowed to happen at any given point of a time for a single vttablet. E.g. by setting transaction cap to 100, there are at most 100 transactions will be processed by a vttablet and the 101th transaction will be blocked (and fail if it cannot get connection within specified timeout) (default 20) + --queryserver-config-transaction-timeout duration query server transaction timeout (in seconds), a transaction will be killed if it takes longer than this value (default 30s) + --queryserver-config-truncate-error-len int truncate errors sent to client if they are longer than this value (0 means do not truncate) + --queryserver-config-txpool-timeout duration query server transaction pool timeout, it is how long vttablet waits if tx pool is full (default 1s) + --queryserver-config-txpool-waiter-cap int query server transaction pool waiter limit, this is the maximum number of transactions that can be queued waiting to get a connection (default 5000) + --queryserver-config-warn-result-size int query server result size warning threshold, warn if number of rows returned from vttablet for non-streaming queries exceeds this + --queryserver-enable-settings-pool Enable pooling of connections with modified system settings (default true) + --queryserver-enable-views Enable views support in vttablet. + --queryserver_enable_online_ddl Enable online DDL. (default true) + --redact-debug-ui-queries redact full queries and bind variables from debug UI + --relay_log_max_items int Maximum number of rows for VReplication target buffering. (default 5000) + --relay_log_max_size int Maximum buffer size (in bytes) for VReplication target buffering. If single rows are larger than this, a single row is buffered at a time. (default 250000) + --remote_operation_timeout duration time to wait for a remote operation (default 15s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --restore-to-pos string (init incremental restore parameter) if set, run a point in time recovery that ends with the given position. This will attempt to use one full backup followed by zero or more incremental backups + --restore-to-timestamp string (init incremental restore parameter) if set, run a point in time recovery that restores up to the given timestamp, if possible. Given timestamp in RFC3339 format. Example: '2006-01-02T15:04:05Z07:00' + --restore_concurrency int (init restore parameter) how many concurrent files to restore at once (default 4) + --restore_from_backup (init restore parameter) will check BackupStorage for a recent backup at startup and start there + --restore_from_backup_ts string (init restore parameter) if set, restore the latest backup taken at or before this timestamp. Example: '2021-04-29.133050' + --retain_online_ddl_tables duration How long should vttablet keep an old migrated table before purging it (default 24h0m0s) + --sanitize_log_messages Remove potentially sensitive information in tablet INFO, WARNING, and ERROR log messages such as query parameters. + --schema-change-reload-timeout duration query server schema change reload timeout, this is how long to wait for the signaled schema reload operation to complete before giving up (default 30s) + --schema-version-max-age-seconds int max age of schema version records to kept in memory by the vreplication historian + --schema_change_signal Enable the schema tracker; requires queryserver-config-schema-change-signal to be enabled on the underlying vttablets for this to work (default true) + --schema_dir string Schema base directory. Should contain one directory per keyspace, with a vschema.json file if necessary. + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --serving_state_grace_period duration how long to pause after broadcasting health to vtgate, before enforcing a new serving state + --shard_sync_retry_delay duration delay between retries of updates to keep the tablet and its shard record in sync (default 30s) + --shutdown_grace_period duration how long to wait (in seconds) for queries and transactions to complete during graceful shutdown. (default 0s) + --sql-max-length-errors int truncate queries in error logs to the given length (default unlimited) + --sql-max-length-ui int truncate queries in debug UIs to the given length (default 512) (default 512) + --srv_topo_cache_refresh duration how frequently to refresh the topology for cached entries (default 1s) + --srv_topo_cache_ttl duration how long to use cached entries for topology (default 1s) + --srv_topo_timeout duration topo server timeout (default 5s) + --start_mysql Should vtcombo also start mysql + --stats_backend string The name of the registered push-based monitoring/stats backend to use + --stats_combine_dimensions string List of dimensions to be combined into a single "all" value in exported stats vars + --stats_common_tags strings Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 + --stats_drop_variables string Variables to be dropped from the list of exported variables. + --stats_emit_period duration Interval between emitting stats to all registered backends (default 1m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --stream_buffer_size int the number of bytes sent from vtgate for each stream call. It's recommended to keep this value in sync with vttablet's query-server-config-stream-buffer-size. (default 32768) + --stream_health_buffer_size uint max streaming health entries to buffer per streaming health client (default 20) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --table_gc_lifecycle string States for a DROP TABLE garbage collection cycle. Default is 'hold,purge,evac,drop', use any subset ('drop' implcitly always included) (default "hold,purge,evac,drop") + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_filters strings Specifies a comma-separated list of 'keyspace|shard_name or keyrange' values to filter the tablets to watch. + --tablet_health_keep_alive duration close streaming tablet health connection if there are no requests for this long (default 5m0s) + --tablet_hostname string if not empty, this hostname will be assumed instead of trying to resolve it + --tablet_manager_grpc_ca string the server ca to use to validate servers when connecting + --tablet_manager_grpc_cert string the cert to use to connect + --tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) + --tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100) + --tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_manager_grpc_key string the key to use to connect + --tablet_manager_grpc_server_name string the server name to use to validate server certificate + --tablet_manager_protocol string Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") + --tablet_refresh_interval duration Tablet refresh interval. (default 1m0s) + --tablet_refresh_known_tablets Whether to reload the tablet's address/port map from topo in case they change. (default true) + --tablet_url_template string Format string describing debug tablet url formatting. See getTabletDebugURL() for how to customize this. (default "http://{{.GetTabletHostPort}}") + --throttle_tablet_types string Comma separated VTTablet types to be considered by the throttler. default: 'replica'. example: 'replica,rdonly'. 'replica' aways implicitly included (default "replica") + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) + --topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server + --topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS + --topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS + --topo_global_root string the path of the global topology data in the global topology server + --topo_global_server_address string the address of the global topology server + --topo_implementation string the topology implementation to use + --topo_read_concurrency int Concurrency of topo reads. (default 32) + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --tracer string tracing service to use (default "noop") + --tracing-enable-logging whether to enable logging in the tracing service + --tracing-sampling-rate float sampling rate for the probabilistic jaeger sampler (default 0.1) + --tracing-sampling-type string sampling strategy to use for jaeger. possible values are 'const', 'probabilistic', 'rateLimiting', or 'remote' (default "const") + --track_schema_versions When enabled, vttablet will store versions of schemas at each position that a DDL is applied and allow retrieval of the schema corresponding to a position + --transaction-log-stream-handler string URL handler for streaming transactions log (default "/debug/txlog") + --transaction_limit_by_component Include CallerID.component when considering who the user is for the purpose of transaction limit. + --transaction_limit_by_principal Include CallerID.principal when considering who the user is for the purpose of transaction limit. (default true) + --transaction_limit_by_subcomponent Include CallerID.subcomponent when considering who the user is for the purpose of transaction limit. + --transaction_limit_by_username Include VTGateCallerID.username when considering who the user is for the purpose of transaction limit. (default true) + --transaction_limit_per_user float Maximum number of transactions a single user is allowed to use at any time, represented as fraction of -transaction_cap. (default 0.4) + --transaction_mode string SINGLE: disallow multi-db transactions, MULTI: allow multi-db transactions with best effort commit, TWOPC: allow multi-db transactions with 2pc commit (default "MULTI") + --truncate-error-len int truncate errors sent to client if they are longer than this value (0 means do not truncate) + --twopc_abandon_age float time in seconds. Any unresolved transaction older than this time will be sent to the coordinator to be resolved. + --twopc_coordinator_address string address of the (VTGate) process(es) that will be used to notify of abandoned transactions. + --twopc_enable if the flag is on, 2pc is enabled. Other 2pc flags must be supplied. + --tx-throttler-config string Synonym to -tx_throttler_config (default "target_replication_lag_sec:2 max_replication_lag_sec:10 initial_rate:100 max_increase:1 emergency_decrease:0.5 min_duration_between_increases_sec:40 max_duration_between_increases_sec:62 min_duration_between_decreases_sec:20 spread_backlog_across_sec:20 age_bad_rate_after_sec:180 bad_rate_increase:0.1 max_rate_approach_threshold:0.9") + --tx-throttler-default-priority int Default priority assigned to queries that lack priority information (default 100) + --tx-throttler-dry-run If present, the transaction throttler only records metrics about requests received and throttled, but does not actually throttle any requests. + --tx-throttler-healthcheck-cells strings Synonym to -tx_throttler_healthcheck_cells + --tx-throttler-tablet-types strings A comma-separated list of tablet types. Only tablets of this type are monitored for replication lag by the transaction throttler. Supported types are replica and/or rdonly. (default replica) + --tx-throttler-topo-refresh-interval duration The rate that the transaction throttler will refresh the topology to find cells. (default 5m0s) + --tx_throttler_config string The configuration of the transaction throttler as a text-formatted throttlerdata.Configuration protocol buffer message. (default "target_replication_lag_sec:2 max_replication_lag_sec:10 initial_rate:100 max_increase:1 emergency_decrease:0.5 min_duration_between_increases_sec:40 max_duration_between_increases_sec:62 min_duration_between_decreases_sec:20 spread_backlog_across_sec:20 age_bad_rate_after_sec:180 bad_rate_increase:0.1 max_rate_approach_threshold:0.9") + --tx_throttler_healthcheck_cells strings A comma-separated list of cells. Only tabletservers running in these cells will be monitored for replication lag by the transaction throttler. + --unhealthy_threshold duration replication lag after which a replica is considered unhealthy (default 2h0m0s) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --vreplication-parallel-insert-workers int Number of parallel insertion workers to use during copy phase. Set <= 1 to disable parallelism, or > 1 to enable concurrent insertion during copy phase. (default 1) + --vreplication_copy_phase_duration duration Duration for each copy phase loop (before running the next catchup: default 1h) (default 1h0m0s) + --vreplication_copy_phase_max_innodb_history_list_length int The maximum InnoDB transaction history that can exist on a vstreamer (source) before starting another round of copying rows. This helps to limit the impact on the source tablet. (default 1000000) + --vreplication_copy_phase_max_mysql_replication_lag int The maximum MySQL replication lag (in seconds) that can exist on a vstreamer (source) before starting another round of copying rows. This helps to limit the impact on the source tablet. (default 43200) + --vreplication_healthcheck_retry_delay duration healthcheck retry delay (default 5s) + --vreplication_healthcheck_timeout duration healthcheck retry delay (default 1m0s) + --vreplication_healthcheck_topology_refresh duration refresh interval for re-reading the topology (default 30s) + --vreplication_heartbeat_update_interval int Frequency (in seconds, default 1, max 60) at which the time_updated column of a vreplication stream when idling (default 1) + --vreplication_max_time_to_retry_on_error duration stop automatically retrying when we've had consecutive failures with the same error for this long after the first occurrence + --vreplication_replica_lag_tolerance duration Replica lag threshold duration: once lag is below this we switch from copy phase to the replication (streaming) phase (default 1m0s) + --vreplication_retry_delay duration delay before retrying a failed workflow event in the replication phase (default 5s) + --vreplication_store_compressed_gtid Store compressed gtids in the pos column of the sidecar database's vreplication table + --vreplication_tablet_type string comma separated list of tablet types used as a source (default "in_order:REPLICA,PRIMARY") + --vschema-persistence-dir string If set, per-keyspace vschema will be persisted in this directory and reloaded into the in-memory topology server across restarts. Bookkeeping is performed using a simple watcher goroutine. This is useful when running vtcombo as an application development container (e.g. vttestserver) where you want to keep the same vschema even if developer's machine reboots. This works in tandem with vttestserver's --persistent_mode flag. Needless to say, this is neither a perfect nor a production solution for vschema persistence. Consider using the --external_topo_server flag if you require a more complete solution. This flag is ignored if --external_topo_server is set. + --vschema_ddl_authorized_users string List of users authorized to execute vschema ddl operations, or '%' to allow all users. + --vstream-binlog-rotation-threshold int Byte size at which a VStreamer will attempt to rotate the source's open binary log before starting a GTID snapshot based stream (e.g. a ResultStreamer or RowStreamer) (default 67108864) + --vstream_dynamic_packet_size Enable dynamic packet sizing for VReplication. This will adjust the packet size during replication to improve performance. (default true) + --vstream_packet_size int Suggested packet size for VReplication streamer. This is used only as a recommendation. The actual packet size may be more or less than this amount. (default 250000) + --vtctld_sanitize_log_messages When true, vtctld sanitizes logging. + --vtgate-config-terse-errors prevent bind vars from escaping in returned errors + --vtgate_grpc_ca string the server ca to use to validate servers when connecting + --vtgate_grpc_cert string the cert to use to connect + --vtgate_grpc_crl string the server crl to use to validate server certificates when connecting + --vtgate_grpc_key string the key to use to connect + --vtgate_grpc_server_name string the server name to use to validate server certificate + --vttablet_skip_buildinfo_tags string comma-separated list of buildinfo tags to skip from merging with --init_tags. each tag is either an exact match or a regular expression of the form '/regexp/'. (default "/.*/") + --wait_for_backup_interval duration (init restore parameter) if this is greater than 0, instead of starting up empty when no backups are found, keep checking at this interval for a backup to appear + --warn_memory_rows int Warning threshold for in-memory results. A row count higher than this amount will cause the VtGateWarnings.ResultsExceeded counter to be incremented. (default 30000) + --warn_payload_size int The warning threshold for query payloads in bytes. A payload greater than this threshold will cause the VtGateWarnings.WarnPayloadSizeExceeded counter to be incremented. + --warn_sharded_only If any features that are only available in unsharded mode are used, query execution warnings will be added to the session + --watch_replication_stream When enabled, vttablet will stream the MySQL replication stream from the local server, and use it to update schema when it sees a DDL. + --xbstream_restore_flags string Flags to pass to xbstream command during restore. These should be space separated and will be added to the end of the command. These need to match the ones used for backup e.g. --compress / --decompress, --encrypt / --decrypt + --xtrabackup_backup_flags string Flags to pass to backup command. These should be space separated and will be added to the end of the command + --xtrabackup_prepare_flags string Flags to pass to prepare command. These should be space separated and will be added to the end of the command + --xtrabackup_root_path string Directory location of the xtrabackup and xbstream executables, e.g., /usr/bin + --xtrabackup_stream_mode string Which mode to use if streaming, valid values are tar and xbstream. Please note that tar is not supported in XtraBackup 8.0 (default "tar") + --xtrabackup_stripe_block_size uint Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) + --xtrabackup_stripes uint If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression + --xtrabackup_user string User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. +``` + diff --git a/content/en/docs/19.0/reference/programs/vtctl/_index.md b/content/en/docs/19.0/reference/programs/vtctl/_index.md new file mode 100644 index 000000000..b0c6fa494 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/_index.md @@ -0,0 +1,268 @@ +--- +title: vtctl +description: vtctl Command Index +aliases: ['/docs/reference/vitess-api/','/docs/reference/vtctl/'] +--- + +`vtctl` is a command-line tool used to administer a Vitess cluster. It is available as both a standalone tool (`vtctl`) and client-server (`vtctlclient` in combination with `vtctld`). Using client-server is recommended, as it provides an additional layer of security when using the client remotely. + +Note that wherever `vtctl` commands produced master or MASTER for tablet type, they now produce primary or PRIMARY. Scripts and tools that depend on parsing command output will need to be updated. + +## Commands + +### Tablets + +| Name | Example Usage | +| :-------- | :--------------- | +| (DEPRECATED) [InitTablet](../vtctl/tablets#inittablet) DEPRECATED | `InitTablet -- [--allow_update] [--allow_different_shard] [--allow_master_override] [--parent] [--db_name_override=] [--hostname=] [--mysql_port=] [--port=] [--grpc_port=] [--tags=tag1:value1,tag2:value2] -keyspace= -shard= ` | +| [GetTablet](../vtctl/tablets#gettablet) | `GetTablet ` | +| (DEPRECATED) [UpdateTabletAddrs](../vtctl/tablets#updatetabletaddrs) DEPRECATED | `UpdateTabletAddrs -- [--hostname ] [--ip-addr ] [--mysql-port ] [--vt-port ] [--grpc-port ] ` | +| [DeleteTablet](../vtctl/tablets#deletetablet) | `DeleteTablet -- [--allow_primary=false] ...` | +| [SetReadOnly](../vtctl/tablets#setreadonly) | `SetReadOnly ` | +| [SetReadWrite](../vtctl/tablets#setreadwrite) | `SetReadWrite ` | +| [StartReplication](../vtctl/tablets#startreplication) | `StartReplication ` | +| [StopReplication](../vtctl/tablets#stopreplication) | `StopReplication ` | +| [ChangeTabletType](../vtctl/tablets#changetablettype) | `ChangeTabletType -- [--dry-run] ` | +| [Ping](../vtctl/tablets#ping) | `Ping ` | +| [RefreshState](../vtctl/tablets#refreshstate) | `RefreshState ` | +| [RefreshStateByShard](../vtctl/tablets#refreshstatebyshard) | `RefreshStateByShard -- [--cells=c1,c2,...] ` | +| [RunHealthCheck](../vtctl/tablets#runhealthcheck) | `RunHealthCheck ` | +| [Sleep](../vtctl/tablets#sleep) | `Sleep ` | +| [ExecuteHook](../vtctl/tablets#executehook) | `ExecuteHook [ ...]` | +| [ExecuteFetchAsApp](../vtctl/tablets#executefetchasapp) | `ExecuteFetchAsApp -- [--max_rows=10000] [--json] [--use_pool] ` | +| [ExecuteFetchAsDba](../vtctl/tablets#executefetchasdba) | `ExecuteFetchAsDba -- [--max_rows=10000] [--disable_binlogs] [--json] ` | +| [VReplicationExec](../vtctl/tablets#vreplicationexec) | `VReplicationExec -- [--json] ` | +| [Backup](../vtctl/tablets#backup) | `Backup -- [--concurrency=4] [--allow_primary=false] [--upgrade-safe=false] [--incremental-from-pos=] ` | +| [RestoreFromBackup](../vtctl/tablets#restorefrombackup) | `RestoreFromBackup ` | +| [ReparentTablet](../vtctl/tablets#reparenttablet) | `ReparentTablet ` | + +### Shards + +| Name | Example Usage | +| :-------- | :--------------- | +| [CreateShard](../vtctl/shards#createshard) | `CreateShard -- [--force] [--parent] ` | +| [GetShard](../vtctl/shards#getshard) | `GetShard ` | +| [ValidateShard](../vtctl/shards#validateshard) | `ValidateShard -- [--ping-tablets] ` | +| [ShardReplicationPositions](../vtctl/shards#shardreplicationpositions) | `ShardReplicationPositions ` | +| [ListShardTablets](../vtctl/shards#listshardtablets) | `ListShardTablets ` | +| [SetShardIsPrimaryServing](../vtctl/shards#setshardisprimaryserving) | `SetShardIsPrimaryServing ` | +| [SetShardTabletControl](../vtctl/shards#setshardtabletcontrol) | `SetShardTabletControl -- [--cells=c1,c2,...] [--denied_tables=t1,t2,...] [--remove] [--disable_query_service] ` | +| [UpdateSrvKeyspacePartition](../vtctl/shards#updatesrvkeyspacepartition)| `UpdateSrvKeyspacePartition -- [--cells=c1,c2,...] [--remove] ` | +| [SourceShardDelete](../vtctl/shards#sourcesharddelete) | `SourceShardDelete ` | +| [SourceShardAdd](../vtctl/shards#sourceshardadd) | `SourceShardAdd -- [--key_range=] [--tables=] ` | +| [ShardReplicationFix](../vtctl/shards#shardreplicationfix) | `ShardReplicationFix ` | +| [WaitForFilteredReplication](../vtctl/shards#waitforfilteredreplication) | `WaitForFilteredReplication -- [--max_delay ] ` | +| [RemoveShardCell](../vtctl/shards#removeshardcell) | `RemoveShardCell -- [--force] [--recursive] ` | +| [DeleteShard](../vtctl/shards#deleteshard) | `DeleteShard -- [--recursive] [--even_if_serving] ...` | +| [ListBackups](../vtctl/shards#listbackups) | `ListBackups ` | +| [BackupShard](../vtctl/shards#backupshard) | `BackupShard -- [--allow_primary=false] [--upgrade-safe=false] ` [--incremental_from_pos=] | +| [RemoveBackup](../vtctl/shards#removebackup) | `RemoveBackup ` | +| (DEPRECATED) [InitShardPrimary](../vtctl/shards#initshardprimary) | `InitShardPrimary -- [--force] [--wait_replicas_timeout=] ` | +| [PlannedReparentShard](../vtctl/shards#plannedreparentshard) | `PlannedReparentShard -- --keyspace_shard= [--new_primary=] [--avoid_tablet=] [--wait_replicas_timeout=]` | +| [EmergencyReparentShard](../vtctl/shards#emergencyreparentshard) | `EmergencyReparentShard -- --keyspace_shard= [--new_primary=] [--wait_replicas_timeout=] [--ignore_replicas=] [--prevent_cross_cell_promotion=]` +| [TabletExternallyReparented](../vtctl/shards#tabletexternallyreparented) | `TabletExternallyReparented ` | +| [GenerateShardRanges](../vtctl/shards#generateshardranges) | `GenerateShardRanges ` | + +### Keyspaces + +| Name | Example Usage | +| :-------- | :--------------- | +| [CreateKeyspace](../vtctl/keyspaces#createkeyspace) | `CreateKeyspace -- [--sharding_column_name=name] [--sharding_column_type=type] [--served_from=tablettype1:ks1,tablettype2:ks2,...] [--force] [--keyspace_type=type] [--base_keyspace=base_keyspace] [--snapshot_time=time] [--durability-policy=policy_name] [--sidecar-db-name=db_name] ` | +| [DeleteKeyspace](../vtctl/keyspaces#deletekeyspace) | `DeleteKeyspace -- [--recursive] ` | +| [RemoveKeyspaceCell](../vtctl/keyspaces#removekeyspacecell) | `RemoveKeyspaceCell -- [--force] [--recursive] ` | +| [GetKeyspace](../vtctl/keyspaces#getkeyspace) | `GetKeyspace ` | +| [GetKeyspaces](../vtctl/keyspaces#getkeyspaces) | `GetKeyspaces ` | +| [RebuildKeyspaceGraph](../vtctl/keyspaces#rebuildkeyspacegraph) | `RebuildKeyspaceGraph -- [--cells=c1,c2,...] ...` | +| [ValidateKeyspace](../vtctl/keyspaces#validatekeyspace) | `ValidateKeyspace -- [--ping-tablets] ` | +| [CreateLookupVindex](../vtctl/keyspaces#createlookupvindex) | `CreateLookupVindex -- [--cell=] [--tablet_types=] ` | +| [ExternalizeVindex](../vtctl/keyspaces#externalizevindex) | `ExternalizeVindex .` | +| [Materialize](../vtctl/keyspaces#materialize) | `Materialize , example : '{"workflow": "aaa", "source_keyspace": "source", "target_keyspace": "target", "table_settings": [{"target_table": "customer", "source_expression": "select * from customer", "create_ddl": "copy"}]}'` | +| [VDiff](../vtctl/keyspaces#vdiff) | `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] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] [] []` | +| [FindAllShardsInKeyspace](../vtctl/keyspaces#findallshardsinkeyspace) | `FindAllShardsInKeyspace ` | + +### Generic + +| Name | Example Usage | +| :-------- | :--------------- | +| [Validate](../vtctl/generic#validate) | `Validate -- [--ping-tablets]` | +| [ListAllTablets](../vtctl/generic#listalltablets) | `ListAllTablets -- [--keyspace=''] [--tablet_type=] [,,...]` | +| [ListTablets](../vtctl/generic#listtablets) | `ListTablets ...` | +| [Help](../vtctl/generic#help) | `Help [command name]` | + +### Schema, Version, Permissions + +| Name | Example Usage | +| :-------- | :--------------- | +| [GetSchema](../vtctl/schema-version-permissions#getschema) | `GetSchema -- [--tables=,,...] [--exclude_tables=,,...] [--include-views] ` | +| [ReloadSchema](../vtctl/schema-version-permissions#reloadschema) | `ReloadSchema ` | +| [ReloadSchemaShard](../vtctl/schema-version-permissions#reloadschemashard) | `ReloadSchemaShard -- [--concurrency=10] [--include_primary=false] ` | +| [ReloadSchemaKeyspace](../vtctl/schema-version-permissions#reloadschemakeyspace) | `ReloadSchemaKeyspace -- [--concurrency=10] [--include_primary=false] ` | +| [ValidateSchemaShard](../vtctl/schema-version-permissions#validateschemashard) | `ValidateSchemaShard -- [--exclude_tables=''] [--include-views] ` | +| [ValidateSchemaKeyspace](../vtctl/schema-version-permissions#validateschemakeyspace) | `ValidateSchemaKeyspace -- [--exclude_tables=''] [--include-views] ` | +| [ApplySchema](../vtctl/schema-version-permissions#applyschema) | `ApplySchema -- [--wait_replicas_timeout=10s] {--sql= \|\| --sql-file=} [--batch-size=100] ` | +| [CopySchemaShard](../vtctl/schema-version-permissions#copyschemashard) | `CopySchemaShard -- [--tables=,,...] [--exclude_tables=,,...] [--include-views] [--skip-verify] [--wait_replicas_timeout=10s] { \|\| } ` | +| [ValidateVersionShard](../vtctl/schema-version-permissions#validateversionshard) | `ValidateVersionShard ` | +| [ValidateVersionKeyspace](../vtctl/schema-version-permissions#validateversionkeyspace) | `ValidateVersionKeyspace ` | +| [GetPermissions](../vtctl/schema-version-permissions#getpermissions) | `GetPermissions ` | +| [ValidatePermissionsShard](../vtctl/schema-version-permissions#validatepermissionsshard) | `ValidatePermissionsShard ` | +| [ValidatePermissionsKeyspace](../vtctl/schema-version-permissions#validatepermissionskeyspace) | `ValidatePermissionsKeyspace ` | +| [GetVSchema](../vtctl/schema-version-permissions#getvschema) | `GetVSchema ` | +| [ApplyVSchema](../vtctl/schema-version-permissions#applyvschema) | `ApplyVSchema -- {--vschema= \|\| --vschema_file= \|\| --sql= \|\| --sql_file=} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run] ` | +| [GetRoutingRules](../vtctl/schema-version-permissions#getroutingrules) | `GetRoutingRules ` | +| [ApplyRoutingRules](../vtctl/schema-version-permissions#applyroutingrules) | `ApplyRoutingRules -- {--rules= \|\| --rules_file=} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run]` | +| [RebuildVSchemaGraph](../vtctl/schema-version-permissions#rebuildvschemagraph) | `RebuildVSchemaGraph -- [--cells=c1,c2,...]` | + +### Serving Graph + +| Name | Example Usage | +| :-------- | :--------------- | +| [GetSrvKeyspaceNames](../vtctl/serving-graph#getsrvkeyspacenames) | `GetSrvKeyspaceNames ` | +| [GetSrvKeyspace](../vtctl/serving-graph#getsrvkeyspace) | `GetSrvKeyspace ` | +| [GetSrvVSchema](../vtctl/serving-graph#getsrvvsvchema) | `GetSrvVSchema ` | +| [DeleteSrvVSchema](../vtctl/serving-graph#deletesrvvschema) | `DeleteSrvVSchema ` | + +### Replication Graph + +| Name | Example Usage | +| :-------- | :--------------- | +| [GetShardReplication](../vtctl/replication-graph#getshardreplication) | `GetShardReplication ` | + +### Cells + +| Name | Example Usage | +| :-------- | :--------------- | +| [AddCellInfo](../vtctl/cells#addcellinfo) | `AddCellInfo -- [--server_address ] [--root ] ` | +| [UpdateCellInfo](../vtctl/cells#updatecellinfo) | `UpdateCellInfo -- [--server_address ] [--root ] ` | +| [DeleteCellInfo](../vtctl/cells#deletecellinfo) | `DeleteCellInfo -- [--force] ` | +| [GetCellInfoNames](../vtctl/cells#getcellinfonames) | `GetCellInfoNames ` | +| [GetCellInfo](../vtctl/cells#getcellinfo) | `GetCellInfo ` | + +### CellsAliases + +| Name | Example Usage | +| :-------- | :--------------- | +| [AddCellsAlias](../vtctl/cell-aliases#addcellsalias) | `AddCellsAlias -- [--cells ] ` | +| [UpdateCellsAlias](../vtctl/cell-aliases#updatecellsalias) | `UpdateCellsAlias -- [--cells ] ` | +| [DeleteCellsAlias](../vtctl/cell-aliases#deletecellsalias) | `DeleteCellsAlias ` | +| [GetCellsAliases](../vtctl/cell-aliases#getcellsaliases) | `GetCellsAliases ` | + +### Topo + +| Name | Example Usage | +| :-------- | :--------------- | +| [TopoCat](../vtctl/topo#topocat) | `TopoCat -- [--cell ] [--decode_proto] [--decode_proto_json] [--long] [...]` | +| [TopoCp](../vtctl/topo#topocp) | `TopoCp -- [--cell ] [--to_topo] ` | + +### Throttler + +| Name | Example Usage | +| :-------- | :--------------- | +| [UpdateThrottlerConfig](../vtctl/throttler#updatethrottlerconfig) | `UpdateThrottlerConfig -- [--enable\|--disable] [--threshold=] [--custom-query=] [--check-as-check-self\|--check-as-check-shard] [--throttle-app|unthrottle-app=] [--throttle-app-ratio=] [--throttle-app-duration=] ` + +## Options + +The following global options apply to `vtctl`: + + +| Name | Type | Definition | +| :------------------------------------ | :--------- | :----------------------------------------------------------------------------------------- | +| --alsologtostderr | | log to standard error as well as files | +| --azblob_backup_account_key_file | string | Path to a file containing the Azure Storage account key; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_KEY will be used as the key itself (NOT a file path) | +| --azblob_backup_account_name | string | Azure Storage Account name for backups; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_NAME will be used | +| --azblob_backup_buffer_size | int | The memory buffer size to use in bytes, per file or stripe, when streaming to Azure Blob Service. (default 104857600) | +| --azblob_backup_container_name | string | Azure Blob Container Name | +| --azblob_backup_parallelism | int | Azure Blob operation parallelism (requires extra memory when increased -- a multiple of azblob_backup_buffer_size). (default 1) | +| --azblob_backup_storage_root | string | Root prefix for all backup-related Azure Blobs; this should exclude both initial and trailing '/' (e.g. just 'a/b' not '/a/b/') | +| --backup_engine_implementation | string | Specifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin") | +| --backup_storage_block_size | int | if backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000) | +| --backup_storage_compress | | if set, the backup files will be compressed (default is true). | +| --backup_storage_implementation | string | which implementation to use for the backup storage feature | +| --backup_storage_number_blocks | int | if backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, at once, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression (default 2) | +| --ceph_backup_storage_config | string | Path to JSON config file for ceph backup storage (default "ceph_backup_config.json") | +| --consul_auth_static_file | string | JSON File to read the topos/tokens from. | +| --datadog-agent-host | string | host to send spans to. if empty, no tracing will be done | +| --datadog-agent-port | string | port to send spans to. if empty, no tracing will be done | +| --detach | | detached mode - run vtcl detached from the terminal | +|-file_backup_storage_root | string | root directory for the file backup storage -- this path must be on shared storage to provide a global view of backups to all vitess components | +| --gcs_backup_storage_bucket | string | Google Cloud Storage bucket to use for backups | +| --gcs_backup_storage_root | string | root prefix for all backup-related object names | +| --grpc_auth_static_client_creds | string | when using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server | +| --grpc_compression | string | how to compress gRPC, default: nothing, supported: snappy | +| --grpc_enable_tracing | | Enable GRPC tracing | +| --grpc_initial_conn_window_size | int | grpc initial connection window size | +| --grpc_initial_window_size | int | grpc initial window size | +| --grpc_keepalive_time | duration | After a duration of this time if the client doesn't see any activity it pings the server to see if the transport is still alive. (default 10s) | +| --grpc_keepalive_timeout | duration | After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) | +| --grpc_max_message_size | int | Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) | +| --grpc_prometheus | | Enable gRPC monitoring with Prometheus | +| --jaeger-agent-host | string | host and port to send spans to. if empty, no tracing will be done | +| --keep_logs | duration | keep logs for this long (using ctime) (zero to keep forever) | +| --keep_logs_by_mtime | duration | keep logs for this long (using mtime) (zero to keep forever) | +| --log_backtrace_at | value | when logging hits line file:N, emit a stack trace | +| --log_dir | string | If non-empty, write log files in this directory | +| --log_err_stacks | | log stack traces for errors | +| --log_rotate_max_size | uint | size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) | +| --logtostderr | | log to standard error instead of files | +| --mysql_server_version | string | MySQL server version to advertise. | +| --pprof | strings | enable profiling | +| --purge_logs_interval | duration | how often try to remove old logs (default 1h0m0s) | +| --remote_operation_timeout | duration | time to wait for a remote operation (default 30s) | +| --s3_backup_aws_endpoint | string | endpoint of the S3 backend (region must be provided) | +| --s3_backup_aws_region | string | AWS region to use (default "us-east-1") | +| --s3_backup_aws_retries | int | AWS request retries (default -1) | +| --s3_backup_force_path_style | | force the s3 path style | +| --s3_backup_log_level | string | determine the S3 loglevel to use from LogOff, LogDebug, LogDebugWithSigning, LogDebugWithHTTPBody, LogDebugWithRequestRetries, LogDebugWithRequestErrors (default "LogOff") | +| --s3_backup_server_side_encryption | string | server-side encryption algorithm (e.g., AES256, aws:kms) | +| --s3_backup_storage_bucket | string | S3 bucket to use for backups | +| --s3_backup_storage_root | string | root prefix for all backup-related object names | +| --s3_backup_tls_skip_verify_cert | | skip the 'certificate is valid' check for SSL connections | +| --security_policy | string | the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) | +| --service_map | value | comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice | +| --sql-max-length-errors | int | truncate queries in error logs to the given length (default unlimited) | +| --sql-max-length-ui | int | truncate queries in debug UIs to the given length (default 512) (default 512) | +| --stderrthreshold | value | logs at or above this threshold go to stderr (default 1) | +| --tablet_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_grpc_cert | string | the cert to use to connect | +| --tablet_grpc_crl | string | the server crl to use to validate server certificates when connecting | +| --tablet_grpc_key | string | the key to use to connect | +| --tablet_grpc_server_name | string | the server name to use to validate server certificate | +| --tablet_manager_grpc_ca | string | the server ca to use to validate servers when connecting | +| --tablet_manager_grpc_cert | string | the cert to use to connect | +| --tablet_manager_grpc_concurrency | int | concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) | +| --tablet_manager_grpc_connpool_size | int | number of tablets to keep tmclient connections open to (default 100) | +| --tablet_manager_grpc_crl | string | the server crl to use to validate server certificates when connecting | +| --tablet_manager_grpc_key | string | the key to use to connect | +| --tablet_manager_grpc_server_name | string | the server name to use to validate server certificate | +| --tablet_manager_protocol | string | the protocol to use to talk to vttablet (default "grpc") | +| --tablet_protocol | string | how to talk to the vttablets (default "grpc") | +| --topo_consul_lock_session_ttl | string | TTL for consul session. | +| --topo_consul_watch_poll_duration | duration | time of the long poll for watch queries. (default 30s) | +| --topo_etcd_lease_ttl | int | Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) | +| --topo_etcd_tls_ca | string | path to the ca to use to validate the server cert when connecting to the etcd topo server | +| --topo_etcd_tls_cert | string | path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS | +| --topo_etcd_tls_key | string | path to the client key to use to connect to the etcd topo server, enables TLS | +| --topo_global_root | string | the path of the global topology data in the global topology server | +| --topo_global_server_address | string | the address of the global topology server | +| --topo_implementation | string | the topology implementation to use | +| --topo_zk_auth_file | string | auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass | +| --topo_zk_base_timeout | duration | zk base timeout (see zk.Connect) (default 30s) | +| --topo_zk_max_concurrency | int | maximum number of pending requests to send to a Zookeeper server. (default 64) | +| --topo_zk_tls_ca | string | the server ca to use to validate servers when connecting to the zk topo server | +| --topo_zk_tls_cert | string | the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS | +| --topo_zk_tls_key | string | the key to use to connect to the zk topo server, enables TLS | +| --tracer | string | tracing service to use (default "noop") | +| --tracing-enable-logging | | whether to enable logging in the tracing service | +| --tracing-sampling-rate | float | sampling rate for the probabilistic jaeger sampler (default 0.1) | +| --tracing-sampling-type | string | sampling strategy to use for | +| --v | value | log level for V logs | +| --version | | print binary version | +| --vmodule | value | comma-separated list of pattern=N settings for file-filtered logging | +| --vtctl_healthcheck_retry_delay | duration | delay before retrying a failed healthcheck (default 5s) | +| --vtctl_healthcheck_timeout | duration | the health check timeout period (default 1m0s) | +| --vtctl_healthcheck_topology_refresh | duration | refresh interval for re-reading the topology (default 30s) | +| --vtgate_grpc_ca | string | the server ca to use to validate servers when connecting | +| --vtgate_grpc_cert | string | the cert to use to connect | +| --vtgate_grpc_crl | string | the server crl to use to validate server certificates when connecting | +| --vtgate_grpc_key | string | the key to use to connect | +| --vtgate_grpc_server_name | string | the server name to use to validate server certificate | +| --wait-time | duration | time to wait on an action (default 24h0m0s) | diff --git a/content/en/docs/19.0/reference/programs/vtctl/cell-aliases.md b/content/en/docs/19.0/reference/programs/vtctl/cell-aliases.md new file mode 100644 index 000000000..74eef73b6 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/cell-aliases.md @@ -0,0 +1,80 @@ +--- +title: vtctl Cell Aliases Command Reference +series: vtctl +docs_nav_title: Cell Aliases +--- + +The following `vtctl` commands are available for administering Cell Aliases. + +## Commands + +### AddCellsAlias + +Defines a group of cells within which replica/rdonly traffic can be routed across cells. By default, Vitess does not allow traffic between replicas that are part of different cells. Between cells that are not in the same group (alias), only primary traffic can be routed. + + +#### Example + +
AddCellsAlias -- [--cells <cell1,cell2,cell3>] <alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | The list of cell names that are members of this alias. | + + +#### Arguments + +* <alias> – Required. Alias name for this grouping. + +#### Errors + +* the <alias> argument is required for the <AddCellsAlias> command This error occurs if the command is not called with exactly one argument. + +### UpdateCellsAlias + +Updates the content of a CellAlias with the provided parameters. Empty values and intersections with other aliases are not supported. + +#### Example + +
UpdateCellsAliases -- [--cells <cell1,cell2,cell3>] <alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string |The list of cell names that are members of this alias. | + + +#### Arguments + +* <alias> – Required. Alias name group to update. + +#### Errors + +* the <alias> argument is required for the <UpdateCellsAlias> command This error occurs if the command is not called with exactly one argument. + +### DeleteCellsAlias + +Deletes the CellsAlias for the provided alias. After deleting an alias, cells that were part of the group are not going to be able to route replica/rdonly traffic to the rest of the cells that were part of the grouping. + +#### Example + +
DeleteCellsAlias <alias>
+ +#### Errors + +* the <alias> argument is required for the <DeleteCellsAlias> command This error occurs if the command is not called with exactly one argument. + +### GetCellsAliases + +Fetches in json format all the existent cells alias groups. + +#### Example + +
GetCellsAliases
+ +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/cells.md b/content/en/docs/19.0/reference/programs/vtctl/cells.md new file mode 100644 index 000000000..9a3c4646a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/cells.md @@ -0,0 +1,114 @@ +--- +title: vtctl Cell Command Reference +series: vtctl +docs_nav_title: Cells +--- + +The following `vtctl` commands are available for administering Cells. + +## Commands + +### AddCellInfo + +Registers a local topology service in a new cell by creating the CellInfo with the provided parameters. The address will be used to connect to the topology service, and we'll put Vitess data starting at the provided root. + +#### Example + +
AddCellInfo -- [--server_address <addr>] [--root <root>] <cell>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| root | string | The root path the topology service is using for that cell. | +| server_address | string | The address the topology service is using for that cell. | + + +#### Arguments + +* <addr> – Required. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <AddCellInfo> command This error occurs if the command is not called with exactly one argument. + +### DeleteCellInfo + +Deletes the CellInfo for the provided cell. The cell cannot be referenced by any Shard record. + +#### Example + +
DeleteCellInfo <cell>
+ +#### Errors + +* the <cell> argument is required for the <DeleteCellInfo> command This error occurs if the command is not called with exactly one argument. + + +### GetCellInfo + +Prints a JSON representation of the CellInfo for a cell. + +#### Example + +
GetCellInfo <cell>
+ +#### Errors + +* the <cell> argument is required for the <GetCellInfo> command This error occurs if the command is not called with exactly one argument. + +### GetCellInfoNames + +Lists all the cells for which we have a CellInfo object, meaning we have a local topology service registered. + +#### Example + +
GetCellInfoNames
+ +#### Errors + +* <GetCellInfoNames> command takes no parameter This error occurs if the command is not called with exactly 0 arguments. + + +### UpdateCellInfo + +Updates the content of a CellInfo with the provided parameters. If a value is empty, it is not updated. The CellInfo will be created if it doesn't exist. + +#### Example + +
UpdateCellInfo -- [--server_address <addr>] [--root <root>] <cell>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :----------- | +| root | string | The root path the topology service is using for that cell. | +| server_address | string | The address the topology service is using for that cell. | + + +#### Arguments + +* <addr> – Required. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <UpdateCellInfo> command This error occurs if the command is not called with exactly one argument. + +### GetCellInfo + +Prints a JSON representation of the CellInfo for a cell. + +#### Example + +
GetCellInfo <cell>
+ +#### Errors + +* the <cell> argument is required for the <GetCellInfo> command This error occurs if the command is not called with exactly one argument. + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/generic.md b/content/en/docs/19.0/reference/programs/vtctl/generic.md new file mode 100644 index 000000000..5a00359f5 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/generic.md @@ -0,0 +1,91 @@ +--- +title: vtctl Generic Command Reference +series: vtctl +docs_nav_title: Generic Commands +--- + +The following generic `vtctl` commands are available for administering Vitess. + +## Commands + +### Validate + +Validates that all nodes reachable from the global replication graph and that all tablets in all discoverable cells are consistent. + +#### Example + +
Validate -- [--ping-tablets]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | + + +### ListAllTablets + +Lists all tablets in an awk-friendly way. + +#### Example + +
ListAllTablets -- [--keyspace=''] [--tablet_type=<primary,replica,rdonly,spare>] [<cell_name1>,<cell_name2>,...]
+ +#### Arguments + +* <cell_name> – Optional. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. This allows you to request server side filtering to exlude tablets in cells not explicitly specified. + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :---------- | +| keyspace | string | (Optional) A keyspace is a logical database. This allows you to request server side filtering to exlude tablets not in this keyspace. | +| tablet_type | string | (Optional) A tablet type is one of PRIMARY,REPLICA,RDONLY,SPARE. This allows you to request server side filtering to exlude tablets not of this type. | + +#### Errors + +* An error will be returned if you specify a non-existent cell or an invalid tablet type. + +### ListTablets + +Lists specified tablets in an awk-friendly way. + +#### Example + +
ListTablets <tablet alias> ...
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <tablet alias> argument is required for the <ListTablets> command This error occurs if the command is not called with at least one argument. + +### GenerateShardRanges + +Generates shard ranges assuming a keyspace with N shards. + +#### Example + +
GenerateShardRanges -- [--num_shards 2]
+ +#### Flags + +| Name | Type | Definition | +| :-------- |:--------| :---------- | +| num_shards | Integer | Number of shards to generate shard ranges for. (default 2) | + +### Help + +Provides help for a command. + +#### Example + +``` +Help [command name] +``` + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/keyspaces.md b/content/en/docs/19.0/reference/programs/vtctl/keyspaces.md new file mode 100644 index 000000000..713960666 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/keyspaces.md @@ -0,0 +1,388 @@ +--- +title: vtctl Keyspace Command Reference +series: vtctl +docs_nav_title: Keyspaces +--- + +The following `vtctl` commands are available for administering Keyspaces. + +## Commands + +### CreateKeyspace + +Creates the specified keyspace. + +#### Example + +
CreateKeyspace -- [--sharding_column_name=name] [--sharding_column_type=type] [--served_from=tablettype1:ks1,tablettype2:ks2,...] [--force] [--keyspace_type=type] [--base_keyspace=base_keyspace] [--snapshot_time=time] [--durability-policy=policy_name] [--sidecar-db-name=db_name] <keyspace name>
+ +#### Flags + +| Name | Type | Definition | +|:---------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| allow_empty_vschema | Boolean | If set this will allow a new keyspace to have no vschema | +| base_keyspace | Boolean | Specifies the base keyspace for a snapshot keyspace type | +| durability-policy | String | Specifies the [durability policy](../../../../user-guides/configuration-basic/durability_policy) to use for the keyspace | +| force | Boolean | Proceeds even if the keyspace already exists | +| keyspace_type | String | Specifies the type of the keyspace. It can be NORMAL or SNAPSHOT. For a SNAPSHOT keyspace you must specify the name of a base_keyspace, and a snapshot_time in UTC, in RFC3339 time format, e.g. 2006-01-02T15:04:05+00:00 | +| sharding_column_name | String | Specifies the column to use for sharding operations | +| sharding_column_type | String | Specifies the type of the column to use for sharding operations | +| sidecar-db-name | String | (Experimental) Specifies the name of the Vitess sidecar database that tablets in this keyspace will use for internal metadata | +| served_from | String | Specifies a comma-separated list of dbtype:keyspace pairs used to serve traffic | +| snapshot_time | String | Specifies the snapshot time for this keyspace | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace name> argument is required for the <CreateKeyspace> command This error occurs if the command is not called with exactly one argument. + +### DeleteKeyspace + +Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace. + +#### Example + +
DeleteKeyspace -- [--recursive] <keyspace>
+Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace.
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| recursive | Boolean | Also recursively delete all shards in the keyspace. | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* must specify the <keyspace> argument for <DeleteKeyspace> This error occurs if the command is not called with exactly one argument. + +### RemoveKeyspaceCell + +Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell. + +#### Example + +
RemoveKeyspaceCell -- [--force] [--recursive] <keyspace> <cell>
+Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell.
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the cell's topology service cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | +| recursive | Boolean | Also delete all tablets in that cell belonging to the specified keyspace. | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <keyspace> and <cell> arguments are required for the <RemoveKeyspaceCell> command This error occurs if the command is not called with exactly 2 arguments. + +### GetKeyspace + +Outputs a JSON structure that contains information about the Keyspace. + +#### Example + +
GetKeyspace <keyspace>
+Outputs a JSON structure that contains information about the Keyspace.
+ +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the <GetKeyspace> command This error occurs if the command is not called with exactly one argument. + +### GetKeyspaces + +Outputs a sorted list of all keyspaces. + +### RebuildKeyspaceGraph + +Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients. + +#### Example + +
RebuildKeyspaceGraph -- [--cells=c1,c2,...] [--allow_partial] <keyspace> ...
+Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients.
+ +#### Flags + +| Name | Type | Definition | +|:--------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------| +| allow_partial | Boolean | Specifies whether a SNAPSHOT keyspace is allowed to serve with an incomplete set of shards. Ignored for all other types of keyspaces | +| cells | String | Specifies a comma-separated list of cells to update | + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <keyspace> argument must be used to specify at least one keyspace when calling the <RebuildKeyspaceGraph> command This error occurs if the command is not called with at least one argument. + + +### ValidateKeyspace + +Validates that all nodes reachable from the specified keyspace are consistent. + +#### Example + +
ValidateKeyspace -- [--ping-tablets] <keyspace name>
+Validates that all nodes reachable from the specified keyspace are consistent.
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Specifies whether all tablets will be pinged during the validation process | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace name> argument is required for the <ValidateKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### FindAllShardsInKeyspace + +Displays all of the shards in the specified keyspace. + +#### Example + +
FindAllShardsInKeyspace <keyspace>
+Displays all of the shards in the specified keyspace.
+ +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the <FindAllShardsInKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### Reshard + +Start a Resharding process. Example: Reshard --cells='zone1,alias1' --tablet_types='PRIMARY,REPLICA,RDONLY' ks.workflow001 -- '0' '-80,80-' + +#### Example + +
Reshard -- [--source_shards=<source_shards>] [--target_shards=<target_shards>] [--cells=<cells>] [--tablet_types=<source_tablet_types>] [--on-ddl=<ddl-action>] [--skip_schema_copy] <action> <keyspace.workflow>
+ +#### Flags + +| Name | Type | Definition | +|:----------------------------|:---------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| all | Boolean | MoveTables only. Move all tables from the source keyspace. Either table_specs or --all needs to be specified. | +| auto_start | Boolean | If false, streams will start in the Stopped state and will need to be explicitly started (default true) | +| cells | String | Cell(s) or CellAlias(es) (comma-separated) to replicate from. | +| drop_foreign_keys | Boolean | If true, tables in the target keyspace will be created without foreign keys. | +| dry_run | Boolean | Does a dry run of SwitchTraffic and only reports the actions to be taken. --dry_run is only supported for SwitchTraffic, ReverseTraffic and Complete. | +| exclude | String | MoveTables only. Tables to exclude (comma-separated) if --all is specified | +| keep_data | Boolean | Do not drop tables or shards (if true, only vreplication artifacts are cleaned up). --keep_data is only supported for Complete and Cancel. | +| keep_routing_rules | Boolean | Do not remove the routing rules for the source keyspace. --keep_routing_rules is only supported for Complete and Cancel. | +| max_replication_lag_allowed | Duration | Allow traffic to be switched only if vreplication lag is below this (in seconds) (default 30s) | +| on-ddl | String | What to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. (default "IGNORE") | +| rename_tables | Boolean | MoveTables only. Rename tables instead of dropping them. --rename_tables is only supported for Complete. | +| reverse_replication | Boolean | Also reverse the replication (default true). --reverse_replication is only supported for SwitchTraffic. (default true) | +| skip_schema_copy | Boolean | Reshard only. Skip copying of schema to target shards | +| source | String | MoveTables only. Source keyspace | +| source_shards | String | Source shards | +| source_time_zone | String | MoveTables only. Specifying this causes any DATETIME fields to be converted from given time zone into UTC | +| stop_after_copy | Boolean | Streams will be stopped once the copy phase is completed | +| tables | String | MoveTables only. A table spec or a list of tables. Either table_specs or --all needs to be specified. | +| tablet_types | String | Source tablet types to replicate from (e.g. PRIMARY, REPLICA, RDONLY). Defaults to --vreplication_tablet_type parameter value for the tablet, which has the default value of in_order:REPLICA,PRIMARY. Note: SwitchTraffic overrides this default and uses in_order:RDONLY,REPLICA,PRIMARY to switch all traffic by default. (default "in_order:REPLICA,PRIMARY") | +| target_shards | String | Reshard only. Target shards | +| timeout | Duration | Specifies the maximum time to wait, in seconds, for vreplication to catch up on primary migrations. The migration will be cancelled on a timeout. --timeout is only supported for SwitchTraffic and ReverseTraffic. (default 30s) | + +#### Arguments + +* <action> - Required. Action must be one of the following: Create, Complete, Cancel, SwitchTraffic, ReverseTrafffic, Show, or Progress. +* <keyspace.workflow> - Required. The name of the keyspace and workflow to be used for the resharding process. The argument value must be a string that does not contain whitespace. + + +### MoveTables + +Move table(s) to another keyspace, table_specs is a list of tables or the tables section of the vschema for the target keyspace. +Example: +```json +{ + "t1": {"column_vindexes": [{"column": "id1", "name": "hash"}]}, + "t2": {"column_vindexes": [{"column": "id2", "name": "hash"}]} +} +``` + +In the case of an unsharded target keyspace the vschema for each table may be empty. +Example: +```json +{ + "t1":{}, + "t2":{} +} +``` + +#### Example + +
MoveTables [--source=<sourceKs>] [--tables=<tableSpecs>] [--cells=<cells>] [--tablet_types=<source_tablet_types>] [--all] [--exclude=<tables>] [--auto_start] [--stop_after_copy] [--on-ddl=<ddl-action>] [--source_shards=<source_shards>] <action> <targetKs.workflow>
+ +#### Flags + +| Name | Type | Definition | +|:----------------------------|:---------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| all | Boolean | MoveTables only. Move all tables from the source keyspace. Either table_specs or --all needs to be specified. | +| auto_start | Boolean | If false, streams will start in the Stopped state and will need to be explicitly started (default true) | +| cells | String | Cell(s) or CellAlias(es) (comma-separated) to replicate from. | +| drop_foreign_keys | Boolean | If true, tables in the target keyspace will be created without foreign keys. | +| dry_run | Boolean | Does a dry run of SwitchTraffic and only reports the actions to be taken. --dry_run is only supported for SwitchTraffic, ReverseTraffic and Complete. | +| exclude | String | MoveTables only. Tables to exclude (comma-separated) if --all is specified | +| keep_data | Boolean | Do not drop tables or shards (if true, only vreplication artifacts are cleaned up). --keep_data is only supported for Complete and Cancel. | +| keep_routing_rules | Boolean | Do not remove the routing rules for the source keyspace. --keep_routing_rules is only supported for Complete and Cancel. | +| max_replication_lag_allowed | Duration | Allow traffic to be switched only if vreplication lag is below this (in seconds) (default 30s) | +| on-ddl | String | What to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. (default "IGNORE") | +| rename_tables | Boolean | MoveTables only. Rename tables instead of dropping them. --rename_tables is only supported for Complete. | +| reverse_replication | Boolean | Also reverse the replication (default true). --reverse_replication is only supported for SwitchTraffic. (default true) | +| skip_schema_copy | Boolean | Reshard only. Skip copying of schema to target shards | +| source | String | MoveTables only. Source keyspace | +| source_shards | String | Source shards | +| source_time_zone | String | MoveTables only. Specifying this causes any DATETIME fields to be converted from given time zone into UTC | +| stop_after_copy | Boolean | Streams will be stopped once the copy phase is completed | +| tables | String | MoveTables only. A table spec or a list of tables. Either table_specs or --all needs to be specified. | +| tablet_types | String | Source tablet types to replicate from (e.g. PRIMARY, REPLICA, RDONLY). Defaults to --vreplication_tablet_type parameter value for the tablet, which has the default value of in_order:REPLICA,PRIMARY. Note: SwitchTraffic overrides this default and uses in_order:RDONLY,REPLICA,PRIMARY to switch all traffic by default. (default "in_order:REPLICA,PRIMARY") | +| target_shards | String | Reshard only. Target shards | +| timeout | Duration | Specifies the maximum time to wait, in seconds, for vreplication to catch up on primary migrations. The migration will be cancelled on a timeout. --timeout is only supported for SwitchTraffic and ReverseTraffic. (default 30s) | + + +#### Arguments + +* <action> - Required. Action must be one of the following: Create, Complete, Cancel, SwitchTraffic, ReverseTrafffic, Show, or Progress. +* <keyspace.workflow> - Required. The name of the keyspace and workflow to be used for the resharding process. The argument value must be a string that does not contain whitespace. + + +### CreateLookupVindex + +Create and backfill a lookup vindex. the json_spec must contain the vindex and colvindex specs for the new lookup. + +#### Example + +
+CreateLookupVindex  -- [--cells=<source_cells>] [--continue_after_copy_with_owner=false] [--tablet_types=<source_tablet_types>] <keyspace> <json_spec>
+Create and backfill a lookup vindex. the json_spec must contain the vindex and colvindex specs for the new lookup.
+
+ +### Flags + +| Name | Type | Definition | +|:-------------------------------|:--------|:--------------------------------------------------------------------------| +| cells | String | Source cells to replicate from. | +| continue_after_copy_with_owner | Boolean | Vindex will continue materialization after copy when an owner is provided | +| tablet_types | String | Source tablet types to replicate from. | + +### Arguments + +* <keyspace> - Required. The name of the keyspace where lookup vindex needs to be created. +* <json_spec> - Required. json specification about how to create the lookup vindex. More information in [user-guides](../../../../user-guides/configuration-advanced/createlookupvindex) + + +### ExternalizeVindex + +Externalize (activate) a lookup vindex backfilled using `CreateLookupVindex`. + +This removes the workflow and vreplication streams associated with the +backfill, and clears the `write_only` flag on the vindex. After this flag is +removed, applications can start using the vindex for lookups. + +#### Example + +
+ExternalizeVindex <keyspace>.<vindex>
+
+ +### Materialize + +Performs materialization based on the json spec. Is used directly to form VReplication rules, with an optional step to copy table structure/DDL. + +#### Example + +
+Materialize -- [--cells=<cells>] [--tablet_types=<source_tablet_types>] <json_spec>
+
+ +#### Flags + +| Name | Type | Definition | +|:-------------|:-------|:---------------------------------------| +| cells | String | Source cells to replicate from. | +| tablet_types | String | Source tablet types to replicate from. | + + +#### Argument + +* - Required. + +Example: +```json +{ + "workflow": "aaa", + "source_keyspace": "source", + "target_keyspace": "target", + "table_settings": [{ + "target_table": "customer", + "source_expression": "select * from customer", + "create_ddl": "copy"}] +} +``` + +### `VDiff` + +Perform a diff of all tables in the workflow + +#### Example + +
+VDiff -- [--source_cell=<cell>] [--target_cell=<cell>] [--tablet_types=in_order:RDONLY,REPLICA,PRIMARY] [--limit=<max rows to diff>] [--tables=<table list>] [--format=json] [--auto-retry] [--verbose] [--max_extra_rows_to_compare=1000] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] <keyspace.workflow> [<action>] [<UUID>]
+
+ +#### Flags + +| Name | Type | Definition | +|:-------------|:-------|:---------------------------------------| +| auto-retry | Boolean | Should this vdiff automatically retry and continue in case of recoverable errors (default true) | +| checksum | Boolean | Use row-level checksums to compare, not yet implemented | +| debug_query | Boolean | Adds a mysql query to the report that can be used for further debugging | +| filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on primary migrations. The migration will be cancelled on a timeout. (default 30s) | +| format | String | Format of report (default "text") | +| limit | Int | Max rows to stop comparing after (default 9223372036854775807) | +| max_extra_rows_to_compare | Int | If there are collation differences between the source and target, you can have rows that are identical but simply returned in a different order from MySQL. We will do a second pass to compare the rows for any actual differences in this case and this flag allows you to control the resources used for this operation. (default 1000) | +| only_pks | Boolean | When reporting missing rows, only show primary keys in the report. | +| sample_pct | Int | How many rows to sample, not yet implemented (default 100) | +| source_cell | String | The source cell to compare from; default is any available cell | +| tables | String | Only run vdiff for these tables in the workflow | +| tablet_types | String | Tablet types for source (PRIMARY is always used on target) (default "in_order:RDONLY,REPLICA,PRIMARY") | +| target_cell | String | The target cell to compare with; default is any available cell | +| v1 | Boolean | Use legacy VDiff v1 | +| verbose | Boolean | Show verbose vdiff output in summaries | +| wait | Boolean | When creating or resuming a vdiff, wait for it to finish before exiting | +| wait-update-interval | Duration |When waiting on a vdiff to finish, check and display the current status this often (default 1m0s) | + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/replication-graph.md b/content/en/docs/19.0/reference/programs/vtctl/replication-graph.md new file mode 100644 index 000000000..a4ab5b269 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/replication-graph.md @@ -0,0 +1,30 @@ +--- +title: vtctl Replication Graph Command Reference +series: vtctl +docs_nav_title: Replication Graph +--- + +The following `vtctl` commands are available for administering the Replication Graph. + +## Commands + +### GetShardReplication + +Outputs a JSON structure that contains information about the ShardReplication. + +#### Example + +
GetShardReplication <cell> <keyspace/shard>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <cell> and <keyspace/shard> arguments are required for the <GetShardReplication> command This error occurs if the command is not called with exactly 2 arguments. + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/schema-version-permissions.md b/content/en/docs/19.0/reference/programs/vtctl/schema-version-permissions.md new file mode 100644 index 000000000..f2a228199 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/schema-version-permissions.md @@ -0,0 +1,384 @@ +--- +title: vtctl Schema, Version, Permissions Command Reference +series: vtctl +docs_nav_title: Schema Versions & Permissions +--- + +The following `vtctl` commands are available for administering Schema, Versions and Permissions. + +## Commands + +### GetSchema + +Displays the full schema for a tablet, or just the schema for the specified tables in that tablet. + +#### Example + +
GetSchema -- [--tables=<table1>,<table2>,...] [--exclude_tables=<table1>,<table2>,...] [--include-views] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the output | +| table_names_only | Boolean | Only displays table names that match | +| tables | string | Specifies a comma-separated list of tables for which we should gather information. Each is either an exact match, or a regular expression of the form /regexp/ | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* The <tablet alias> argument is required for the <GetSchema> command This error occurs if the command is not called with exactly one argument. + + +### ReloadSchema + +Reloads the schema on a remote tablet. + +#### Example + +
ReloadSchema <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* The <tablet alias> argument is required for the <ReloadSchema> command This error occurs if the command is not called with exactly one argument. + +### ReloadSchemaShard + +Reloads the schema on all the tablets in a shard. + +#### Example + +
ReloadSchemaShard -- [--concurrency=10] [--include_primary=false] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | How many tablets to reload in parallel | +| include_primary | Boolean | Include the primary tablet | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* The <keyspace/shard> argument is required for the <ReloadSchemaShard> command This error occurs if the command is not called with exactly one argument. + +### ReloadSchemaKeyspace + +Reloads the schema on all the tablets in a keyspace. + +#### Example + +
ReloadSchemaKeyspace -- [--concurrency=10] [--include_primary=false] <keyspace>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | How many tablets to reload in parallel | +| include_primary | Boolean | Include the primary tablet(s) | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* The <keyspace> argument is required for the <ReloadSchemaKeyspace> command This error occurs if the command is not called with exactly one argument. + +### ValidateSchemaShard + +Validates that the schema on the primary tablet matches all of the replicas. + +#### Example + +
ValidateSchemaShard -- [--exclude_tables=''] [-include-views] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the validation | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* The <keyspace/shard> argument is required for the <ValidateSchemaShard> command This error occurs if the command is not called with exactly one argument. + +### ValidateSchemaKeyspace + +Validates that the schema on the primary tablet for shard 0 matches the schema on all of the other tablets in the keyspace. + +#### Example + +
ValidateSchemaKeyspace -- [--exclude_tables=''] [--include-views] <keyspace name>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the validation | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* The <keyspace name> argument is required for the <ValidateSchemaKeyspace> command This error occurs if the command is not called with exactly one argument. + +### ApplySchema + +Applies the schema change to the specified keyspace on all shards. The recommended method of applying schema changes is via [Online DDL](../../../../user-guides/schema-changes/managed-online-schema-changes/), which ensures migrations are non-blocking and keeps replication in sync throughout the operation. --ddl_strategy is used to instruct migrations via vreplication, `gh-ost` or `pt-osc` with optional parameters. -request_context allows the user to specify a custom request context for online DDL migrations. + +#### Example + +
ApplySchema -- [--wait_replicas_timeout=10s] [--ddl_strategy=] [--request_context=] {--sql=<sql> || --sql-file=<filename>} <keyspace>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| caller_id | string | Effective caller ID used for the operation and should map to an ACL name which grants this identity the necessary permissions to perform the operation (this is only necessary when strict table ACLs are used). | +| ddl_strategy | string | Online DDL strategy, compatible with @@ddl_strategy session variable (examples: 'gh-ost', 'pt-osc', 'gh-ost --max-load=Threads_running=100' (default "direct"). | +| request_context | string | For Only DDL, optionally supply a custom unique string used as context for the migration(s) in this command. By default a unique context is auto-generated by Vitess. | +| sql | string | A list of semicolon-delimited SQL commands. | +| sql-file | string | Identifies the file that contains the SQL commands. This file needs to exist on the server, rather than on the client. | +| wait_replicas_timeout | Duration | The amount of time to wait for replicas to receive the schema change via replication (default 10s). | + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* The <keyspace> argument is required for the command<ApplySchema> command This error occurs if the command is not called with exactly one argument. +* If using a file you may need to pass the absolute path. + +### CopySchemaShard + +Copies the schema from a source shard's primary (or a specific tablet) to a destination shard. The schema is applied directly on the primary of the destination shard, and it is propagated to the replicas through binlogs. + +#### Example + +
CopySchemaShard -- [--tables=<table1>,<table2>,...] [--exclude_tables=<table1>,<table2>,...] [--include-views] [--wait_replicas_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the output | +| tables | string | Specifies a comma-separated list of tables to copy. Each is either an exact match, or a regular expression of the form /regexp/ | +| wait_replicas_timeout | Duration | The amount of time to wait for replicas to receive the schema change via replication. | + + +#### Arguments + +* <source keyspace/shard> – Required. A keyspace or shard to be used as the source of the copy. +* <source tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <destination keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* The <source keyspace/shard> and <destination keyspace/shard> arguments are both required for the <CopySchemaShard> command. Instead of the <source keyspace/shard> argument, you can also specify <tablet alias> which refers to a specific tablet of the shard in the source keyspace This error occurs if the command is not called with exactly 2 arguments. + +### ValidateVersionShard + +Validates that the version on the primary matches all of the replicas. + +#### Example + +
ValidateVersionShard <keyspace/shard>
+ +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* The <keyspace/shard> argument is required for the <ValidateVersionShard> command This error occurs if the command is not called with exactly one argument. + +### ValidateVersionKeyspace + +Validates that the version on the primary of shard 0 matches all of the other tablets in the keyspace. + +#### Example + +
ValidateVersionKeyspace <keyspace name>
+ +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* The <keyspace name> argument is required for the <ValidateVersionKeyspace> command This error occurs if the command is not called with exactly one argument. + +### GetPermissions + +Displays the permissions for a tablet. + +#### Example + +
GetPermissions <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* The <tablet alias> argument is required for the <GetPermissions> command This error occurs if the command is not called with exactly one argument. + +### ValidatePermissionsShard + +Validates that the permissions on the primary tablet match all the replicas. + +#### Example + +
ValidatePermissionsShard <keyspace/shard>
+ +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* The <keyspace/shard> argument is required for the <ValidatePermissionsShard> command This error occurs if the command is not called with exactly one argument. + +### ValidatePermissionsKeyspace + +Validates that the permissions on the primary of shard 0 match those of all of the other tablets in the keyspace. + +#### Example + +
ValidatePermissionsKeyspace <keyspace name>
+ +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* The <keyspace name> argument is required for the <ValidatePermissionsKeyspace> command This error occurs if the command is not called with exactly one argument. + +### GetVSchema + +Displays the VTGate routing schema. + +#### Example + +
GetVSchema <keyspace>
+ +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* The <keyspace> argument is required for the <GetVSchema> command This error occurs if the command is not called with exactly one argument. + +### ApplyVSchema + +Applies the VTGate routing schema to the provided keyspace. Shows the result after application. + +#### Example + +
ApplyVSchema -- {--vschema=<vschema> || --vschema_file=<vschema file> || --sql=<sql> || --sql_file=<sql file>} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run]<keyspace>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set. | +| dry-run | Boolean | If set, do not save the altered vschema, simply echo to console. | +| skip_rebuild | Boolean | If set, do not rebuild the SrvSchema objects. | +| sql | add vindex | A vschema ddl SQL statement (e.g. add vindex, `alter table t add vindex hash(id)`, etc) | +| sql_file | add vindex | A vschema ddl SQL statement (e.g. add vindex, `alter table t add vindex hash(id)`, etc) | +| vschema | string | Identifies the VTGate routing schema | +| vschema_file | string | Identifies the VTGate routing schema file | + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* The <keyspace> argument is required for the <ApplyVSchema> command. This error occurs if the command is not called with exactly one argument. +* Either the <vschema> or <vschema>File flag must be specified when calling the <ApplyVSchema> command. +* If using a file you may need to pass the absolute path. + +#### Warnings + +* In some cases, unknown params passed to Vindexes may be accepted but reported as warnings in the command response. + +### GetRoutingRules + +``` +GetRoutingRules +``` + +### ApplyRoutingRules + +Applies the VSchema routing rules. + +#### Example + +``` +ApplyRoutingRules -- {--rules= | --rules_file=} [--cells=c1,c2,...] [--skip_rebuild] [--dry-run] +``` + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skip_rebuild is set. | +| dry-run | Boolean | If set, do not save the altered vschema, simply echo to console. | +| skip_rebuild | Boolean | If set, do not rebuild the SrvSchema objects. | +| rules | string | Specify rules as a string. | +| rules_file | string | Specify rules in a file. | + + +### RebuildVSchemaGraph + +Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided). + +#### Example + +
RebuildVSchemaGraph -- [--cells=c1,c2,...]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to look for tablets | + + +#### Errors + +* <RebuildVSchemaGraph> doesn't take any arguments This error occurs if the command is not called with exactly 0 arguments. + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/serving-graph.md b/content/en/docs/19.0/reference/programs/vtctl/serving-graph.md new file mode 100644 index 000000000..0c756ce11 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/serving-graph.md @@ -0,0 +1,70 @@ +--- +title: vtctl Serving Graph Command Reference +series: vtctl +docs_nav_title: Serving Graph +--- + +The following `vtctl` commands are available for administering the Serving Graph. + +## Commands + +### GetSrvKeyspaceNames + +Outputs a list of keyspace names. + +#### Example + +
GetSrvKeyspaceNames <cell>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <GetSrvKeyspaceNames> command This error occurs if the command is not called with exactly one argument. + + +### GetSrvKeyspace + +Outputs a JSON structure that contains information about the SrvKeyspace. + +#### Example + +
GetSrvKeyspace <cell> <keyspace>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <cell> and <keyspace> arguments are required for the <GetSrvKeyspace> command This error occurs if the command is not called with exactly 2 arguments. + +### GetSrvVSchema + +Outputs a JSON structure that contains information about the SrvVSchema. + +#### Example + +
GetSrvVSchema <cell>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <GetSrvVSchema> command This error occurs if the command is not called with exactly one argument. + +### DeleteSrvVSchema + +``` +DeleteSrvVSchema +``` + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/shards.md b/content/en/docs/19.0/reference/programs/vtctl/shards.md new file mode 100644 index 000000000..66e70fc6d --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/shards.md @@ -0,0 +1,467 @@ +--- +title: vtctl Shard Command Reference +series: vtctl +docs_nav_title: Shards +aliases: ['/docs/reference/vtctl/shards/'] +--- + +The following `vtctl` commands are available for administering shards. + +## Commands + +### CreateShard + +Creates the specified shard. + +#### Example + +
CreateShard -- [--force] [--parent] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds with the command even if the keyspace already exists | +| parent | Boolean | Creates the parent keyspace if it doesn't already exist | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <CreateShard> command This error occurs if the command is not called with exactly one argument. + +### GetShard + +Outputs a JSON structure that contains information about the Shard. + +#### Example + +
GetShard <keyspace/shard>
+ +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <GetShard> command This error occurs if the command is not called with exactly one argument. + +### ValidateShard + +Validates that all nodes that are reachable from this shard are consistent. + +#### Example + +
ValidateShard -- [--ping-tablets] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ValidateShard> command This error occurs if the command is not called with exactly one argument. + +### ShardReplicationPositions + +Shows the replication status of each replica machine in the shard graph. In this case, the status refers to the replication lag between the primary vttablet and the replica vttablet. In Vitess, data is always written to the primary vttablet first and then replicated to all replica vttablets. Output is sorted by tablet type, then replication position. Use ctrl-C to interrupt command and see partial result if needed. + +#### Example + +
ShardReplicationPositions <keyspace/shard>
+ +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ShardReplicationPositions> command This error occurs if the command is not called with exactly one argument. + + +### ListShardTablets + +Lists all tablets in the specified shard. + +#### Example + +
ListShardTablets <keyspace/shard>
+ +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ListShardTablets> command This error occurs if the command is not called with exactly one argument. + +### SetShardIsPrimaryServing + +``` +SetShardIsPrimaryServing +``` + +### SetShardTabletControl + +Sets the shardTabletControls or the tabletControls records for a shard and tablet type in the topology service. Only use this for an emergency fix or after a corrupted MoveTables action. Always specify the `denied_tables` flag for MoveTables, but never for Reshard operations. + +To set the `queryServiceDisabled` for the tablet, set `disable_query_service` to true; to unset the queryServiceDisabled provide `denied_tables` with an empty table set. Useful to fix vReplication operations gone wrong. These specific flags update the values for `shardTabletControls` in the topology path: `/keyspaces//SrvKeyspace`. + +{{< warning >}} +It is important to note here the queryServiceDisabled can not be removed by `disable_query_service=false` or the `remove` flags. Only `denied_tables=""` will remove this setting. +{{< /warning >}} + +To change the `deniedTables` list, specify the `denied_tables` parameter with the new list, this is useful to fix tables that are being errantly blocked. To remove the tabletControls for selected tables, use the `remove` flag. These specific flags update the values for `tabletControls` in the topology path: `/keyspaces//shards//Shard`. + +The `SetShardTabletControl` only updates the topology records for a given shard and type, you still need to run [RefreshStateByShard](../tablets#refreshstatebyshard) to inform the vttablets of the topology change. + +#### Examples + +
SetShardTabletControl -- [--cells=c1,c2,...] [--denied_tables=t1,t2,...] [--remove] [--disable_query_service] <keyspace/shard> <tablet type>
+ +**Disable serving of the listed tables for the selected keyspace/shard and tablet type:** + +
SetShardTabletControl -- [--denied_tables=t1,t2,...] <keyspace/shard> <tablet type>

+RefreshStateByShard <keyspace/shard>
+ +**Serve all tables for the selected keyspace/shard and tablet type:** + +
SetShardTabletControl -- --remove <keyspace/shard> <tablet type>

+RefreshStateByShard <keyspace/shard>
+ +**Disable serving for the selected keyspace/shard and tablet type:** + +
SetShardTabletControl -- --disable_query_service=true <keyspace/shard> <tablet type>

+RefreshStateByShard <keyspace/shard>
+ +**Enable serving for the selected keyspace/shard and tablet type:** + +
SetShardTabletControl -- --denied_tables="" <keyspace/shard> <tablet type>

+RefreshStateByShard <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- |:------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| denied_tables | string | Specifies a comma-separated list of tables to deny queries on. Each is either an exact match, or a regular expression of the form '/regexp/'. | +| cells | string | Specifies a comma-separated list of cells to update | +| disable_query_service | Boolean | Disables query service on the provided nodes. This flag requires 'denied_tables' and 'remove' to be unset, otherwise it's ignored. | +| remove | Boolean | Removes cells for MoveTables. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A replicated copy of data that is offline to queries other than for backup purposes + * batch – A replicated copy of data for OLAP load patterns (typically for MapReduce jobs) + * experimental – A replicated copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential primary. Vitess also does not worry about lag for experimental tablets when reparenting. + * primary – A primary copy of data + * master – Deprecated, same as primary + * rdonly – A replicated copy of data for OLAP load patterns + * replica – A replicated copy of data ready to be promoted to primary + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * spare – A replicated copy of data that is ready but not serving query traffic. The data could be a potential primary tablet. + + +#### Errors + +* the <keyspace/shard> and <tablet type> arguments are both required for the <SetShardTabletControl> command This error occurs if the command is not called with exactly 2 arguments. + +### UpdateSrvKeyspacePartition + +``` +UpdateSrvKeyspacePartition -- [--cells=c1,c2,...] [--remove] +``` + +### SourceShardDelete + +Deletes the SourceShard record with the provided index. This is meant as an emergency cleanup function. It does not call RefreshState for the shard primary. + +#### Example + +
SourceShardDelete <keyspace/shard> <uid>
+ +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <uid> – Required. + +#### Errors + +* the <keyspace/shard> and <uid> arguments are both required for the <SourceShardDelete> command This error occurs if the command is not called with at least 2 arguments. + +### SourceShardAdd + +Adds the SourceShard record with the provided index. This is meant as an emergency function. It does not call RefreshState for the shard primary. + +#### Example + +
SourceShardAdd -- [--key_range=<keyrange>] [--tables=<table1,table2,...>] <keyspace/shard> <uid> <source keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| key_range | string | Identifies the key range to use for the SourceShard | +| tables | string | Specifies a comma-separated list of tables to replicate. Each is either an exact match, or a regular expression of the form /regexp/ | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <uid> – Required. +* <source keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard>, <uid>, and <source keyspace/shard> arguments are all required for the <SourceShardAdd> command This error occurs if the command is not called with exactly 3 arguments. + +### ShardReplicationFix + +Walks through a ShardReplication object and fixes the first error that it encounters. + +#### Example + +
ShardReplicationFix <cell> <keyspace/shard>
+ +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <cell> and <keyspace/shard> arguments are required for the ShardReplicationRemove command This error occurs if the command is not called with exactly 2 arguments. + +### WaitForFilteredReplication + +Blocks until the specified shard has caught up with the filtered replication of its source shard. + +#### Example + +
WaitForFilteredReplication -- [--max_delay <max_delay, default 30s>] <keyspace/shard>
+ +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <WaitForFilteredReplication> command This error occurs if the command is not called with exactly one argument. + +### RemoveShardCell + +Removes the cell from the shard's Cells list. + +#### Example + +
RemoveShardCell -- [--force] [--recursive] <keyspace/shard> <cell>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the cell's topology service cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | +| recursive | Boolean | Also delete all tablets in that cell belonging to the specified shard. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <keyspace/shard> and <cell> arguments are required for the <RemoveShardCell> command This error occurs if the command is not called with exactly 2 arguments. + +### DeleteShard + +Deletes the specified shard(s). In recursive mode, it also deletes all tablets belonging to the shard. Otherwise, there must be no tablets left in the shard. + +#### Example + +
DeleteShard -- [--recursive] [--even_if_serving] <keyspace/shard> ...
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| even_if_serving | Boolean | Remove the shard even if it is serving. Use with caution. | +| recursive | Boolean | Also delete all tablets belonging to the shard. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <keyspace/shard> argument must be used to identify at least one keyspace and shard when calling the <DeleteShard> command This error occurs if the command is not called with at least one argument. + +### ListBackups + +Lists all the backups for a shard. + +#### Example + +
ListBackups <keyspace/shard>
+ +#### Errors + +* action <ListBackups> requires <keyspace/shard> This error occurs if the command is not called with exactly one argument. + +### BackupShard + +``` +BackupShard -- [--allow_primary=false] [--upgrade-safe=false] [--incremental-from-pos=] +``` + +### RemoveBackup + +Removes a backup from the BackupStorage. + +#### Example + +
RemoveBackup <keyspace/shard> <backup name>
+ +#### Arguments + +* <backup name> – Required. + +#### Errors + +* action <RemoveBackup> requires <keyspace/shard> <backup name> This error occurs if the command is not called with exactly 2 arguments. + +### InitShardPrimary + +This command has been deprecated. Please use PlannedReparentShard instead. + +Sets the initial primary for a shard. Will make all other tablets in the shard replicas of the provided primary. WARNING: this could cause data loss on an already replicating shard. + +#### Example + +
InitShardPrimary -- [--force] [--wait_replicas_timeout=<duration>] <keyspace/shard> <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | will force the reparent even if the provided tablet is not writable or the shard primary | +| wait_replicas_timeout | Duration | time to wait for replicas to catch up in reparenting | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <InitShardPrimary> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments. +* active reparent commands disabled (unset the --disable_active_reparents flag to enable) + +### PlannedReparentShard + +Reparents the shard to a new primary that can either be explicitly specified, +or chosen by Vitess. Both the existing primary and new primary need to be up +and running to use this command. If the existing primary for the shard is +down, you should use [EmergencyReparentShard](#emergencyreparentshard) instead. + +If the `new_primary` flag is not provided, Vitess will try to automatically +choose a replica to promote to primary, avoiding any replicas specified in +the `avoid_tablet` flag, if provided. Note that Vitess **will not consider +any replicas outside the cell the current primary is in for promotion**, +therefore you **must** pass the `new_primary` flag if you need to promote +a replica in a different cell from the primary. In the automated selection +mode Vitess will prefer the most advanced replica for promotion, to minimize +failover time. + +#### Example + +
PlannedReparentShard -- --keyspace_shard=<keyspace/shard> [--new_primary=<tablet alias>] [--avoid_tablet=<tablet alias>]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| avoid_tablet | string | alias of a tablet that should not be the primary, i.e. reparent to any replica other than this one | +| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | +| new_primary | string | alias of a tablet that should be the new primary | +| wait_replicas_timeout | Duration | time to wait for replicas to catch up in reparenting | + + +#### Errors + +* action <PlannedReparentShard> requires --keyspace_shard=<keyspace/shard> [--new_primary=<tablet alias>] [--avoid_tablet=<tablet alias>] This error occurs if the command is not called with exactly 0 arguments. +* active reparent commands disabled (unset the --disable_active_reparents flag to enable) +* cannot use legacy syntax and flags --<keyspace_shard> and --<new_primary> for action <PlannedReparentShard> at the same time + +### EmergencyReparentShard + +Reparents the shard to the new primary. Assumes the old primary is dead and not responding. + +#### Example + +
EmergencyReparentShard -- --keyspace_shard=<keyspace/shard> -new_primary=<tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | +| new_primary | string | alias of a tablet that should be the new primary | +| wait_replicas_timeout | Duration | time to wait for replicas to catch up in reparenting | + + +#### Errors + +* action <EmergencyReparentShard> requires --keyspace_shard=<keyspace/shard> --new_primary=<tablet alias> This error occurs if the command is not called with exactly 0 arguments. +* active reparent commands disabled (unset the --disable_active_reparents flag to enable) +* cannot use legacy syntax and flag --<new_primary> for action <EmergencyReparentShard> at the same time + + +### TabletExternallyReparented + +Changes metadata in the topology service to acknowledge a shard primary change performed by an external tool. See [Reparenting](../../../../user-guides/configuration-advanced/reparenting/#external-reparenting) for more information. + +#### Example + +
TabletExternallyReparented <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet to promote to primary. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <TabletExternallyReparented> command This error occurs if the command is not called with exactly one argument. + +### GenerateShardRanges + +Generates shard ranges assuming a keyspace with N shards. + +#### Example + +
GenerateShardRanges -- --num_shards=<N>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| num_shards | int | Number of shards to generate shard ranges for. (default 2) | + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/tablets.md b/content/en/docs/19.0/reference/programs/vtctl/tablets.md new file mode 100644 index 000000000..915415109 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/tablets.md @@ -0,0 +1,437 @@ +--- +title: vtctl Tablet Command Reference +series: vtctl +docs_nav_title: Tablets +--- + +The following `vtctl` commands are available for administering tablets. + +## Commands + +### InitTablet + +Deprecated. It is no longer necessary to run this command to initialize a tablet's record in the topology. Starting up a vttablet ensures that the tablet record is eventually published. + +#### Example + +
InitTablet -- [--allow_update] [--allow_different_shard] [--allow_master_override] [--parent] [--db_name_override=<db name>] [--hostname=<hostname>] [--mysql_port=<port>] [--port=<port>] [--grpc_port=<port>] -keyspace=<keyspace> --shard=<shard> <tablet alias> <tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| allow_master_override | Boolean | Use this flag to force initialization if a tablet is created as primary, and a primary for the keyspace/shard already exists. Use with caution. | +| allow_update | Boolean | Use this flag to force initialization if a tablet with the same name already exists. Use with caution. | +| db_name_override | string | Overrides the name of the database that the vttablet uses | +| grpc_port | Int | The gRPC port for the vttablet process | +| hostname | string | The server on which the tablet is running | +| keyspace | string | The keyspace to which this tablet belongs | +| mysql_host | string | The mysql host for the mysql server | +| mysql_port | Int | The mysql port for the mysql server | +| parent | Boolean | Creates the parent shard and keyspace if they don't yet exist | +| port | Int | The main port for the vttablet process | +| shard | string | The shard to which this tablet belongs | +| tags | string | A comma-separated list of key:value pairs that are used to tag the tablet | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A replicated copy of data that is offline to queries other than for backup purposes + * batch – A replicated copy of data for OLAP load patterns (typically for MapReduce jobs) + * experimental – A replicated copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential primary. Vitess also does not worry about lag for experimental tablets when reparenting. + * primary – A primary copy of data + * master – Deprecated, same as primary + * rdonly – A replicated copy of data for OLAP load patterns + * replica – A replicated copy of data ready to be promoted to primary + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * spare – A replicated copy of data that is ready but not serving query traffic. The data could be a potential primary tablet. + + +#### Errors + +* the <tablet alias> and <tablet type> arguments are both required for the <InitTablet> command This error occurs if the command is not called with exactly 2 arguments. + + +### GetTablet + +Outputs a JSON structure that contains information about the Tablet. + +#### Example + +
GetTablet <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <GetTablet> command This error occurs if the command is not called with exactly one argument. + + +### IgnoreHealthError + +Deprecated. + +### UpdateTabletAddrs + +Deprecated. Updates the IP address and port numbers of a tablet. + +#### Example + +
UpdateTabletAddrs -- [--hostname <hostname>] [--ip-addr <ip addr>] [--mysql-port <mysql port>] [--vt-port <vt port>] [--grpc-port <grpc port>] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| grpc-port | Int | The gRPC port for the vttablet process | +| hostname | string | The fully qualified host name of the server on which the tablet is running. | +| mysql-port | Int | The mysql port for the mysql daemon | +| mysql_host | string | The mysql host for the mysql server | +| vt-port | Int | The main port for the vttablet process | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <UpdateTabletAddrs> command This error occurs if the command is not called with exactly one argument. + +### DeleteTablet + +Deletes tablet(s) from the topology. + +#### Example + +
DeleteTablet -- [--allow_primary] <tablet alias> ...
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| allow_primary | Boolean | Allows for the primary tablet of a shard to be deleted. Use with caution. | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <tablet alias> argument must be used to specify at least one tablet when calling the <DeleteTablet> command This error occurs if the command is not called with at least one argument. + +### SetReadOnly + +Sets the tablet as read-only. + +#### Example + +
SetReadOnly <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <SetReadOnly> command This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### SetReadWrite + +Sets the tablet as read-write. + +#### Example + +
SetReadWrite <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <SetReadWrite> command This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### StartReplication + +Starts replication on the specified tablet. + +#### Example + +
StartReplication <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <StartReplication> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### StopReplication + +Stops replication on the specified tablet. + +#### Example + +
StopReplication <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <StopReplication> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + +### ChangeTabletType + +Changes the db type for the specified tablet, if possible. This command is used primarily to arrange replicas, and it will not convert a primary.

NOTE: This command automatically updates the serving graph.

+ +#### Example + +
ChangeTabletType -- [--dry-run] <tablet alias> <tablet type>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| dry-run | Boolean | Lists the proposed change without actually executing it | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A replicated copy of data that is offline to queries other than for backup purposes + * batch – A replicated copy of data for OLAP load patterns (typically for MapReduce jobs) + * experimental – A replicated copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential primary. Vitess also does not worry about lag for experimental tablets when reparenting. + * primary – A primary copy of data + * master – Deprecated, same as primary + * rdonly – A replicated copy of data for OLAP load patterns + * replica – A replicated copy of data ready to be promoted to primary + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * spare – A replicated copy of data that is ready but not serving query traffic. The data could be a potential primary tablet. + +#### Errors + +* the <tablet alias> and <db type> arguments are required for the <ChangeTabletType> command This error occurs if the command is not called with exactly 2 arguments. +* failed reading tablet %v: %v +* invalid type transition %v: %v --> %v + +### Ping + +hecks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations. + +#### Example + +
Ping <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <Ping> command This error occurs if the command is not called with exactly one argument. + +### RefreshState + +Reloads the tablet record on the specified tablet. + +#### Example + +
RefreshState <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <RefreshState> command This error occurs if the command is not called with exactly one argument. + +### RefreshStateByShard + +Runs 'RefreshState' on all tablets in the given shard. + +#### Example + +
RefreshStateByShard -- [--cells=c1,c2,...] <keyspace/shard>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <RefreshStateByShard> command This error occurs if the command is not called with exactly one argument. + +### RunHealthCheck + +Runs a health check on a remote tablet. + +#### Example + +
RunHealthCheck <tablet alias>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <RunHealthCheck> command This error occurs if the command is not called with exactly one argument. +* this only reports an error if a "healthcheck" RPC call to a vttablet fails. It is only useful as a connectivity and vttablet liveness check. + +### Sleep + +Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing. + +#### Example + +
Sleep <tablet alias> <duration>
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <duration> – Required. The amount of time that the action queue should be blocked. The value is a string that contains a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "1h45m". See the definition of the Go language's ParseDuration function for more details. Note that, in practice, the value should be a positively signed value. + +#### Errors + +* the <tablet alias> and <duration> arguments are required for the <Sleep> command This error occurs if the command is not called with exactly 2 arguments. + +### ExecuteHook + +Runs the specified hook on the given tablet. A hook is a script that resides in the $VTROOT/vthook directory. You can put any script into that directory and use this command to run that script.

For this command, the param=value arguments are parameters that the command passes to the specified hook. + +#### Example + +
ExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> ...]
+ +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <hook name> – Required. +* <param1=value1> <param2=value2> . – Optional. + +#### Errors + +* the <tablet alias> and <hook name> arguments are required for the <ExecuteHook> command This error occurs if the command is not called with at least 2 arguments. + +### ExecuteFetchAsApp + +``` +ExecuteFetchAsApp -- [--max_rows=10000] [--json] [--use_pool] +``` + +### ExecuteFetchAsDba + +Runs the given SQL command as a DBA on the remote tablet. + +#### Example + +
ExecuteFetchAsDba -- [--max_rows=10000] [--disable_binlogs] [--json] <tablet alias> <sql command>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| disable_binlogs | Boolean | Disables writing to binlogs during the query | +| json | Boolean | Output JSON instead of human-readable table | +| max_rows | Int | Specifies the maximum number of rows to allow in reset | +| reload_schema | Boolean | Indicates whether the tablet schema will be reloaded after executing the SQL command. The default value is false, which indicates that the tablet schema will not be reloaded. | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <sql command> – Required. + +#### Errors + +* the <tablet alias> and <sql command> arguments are required for the <ExecuteFetchAsDba> command This error occurs if the command is not called with exactly 2 arguments. + +### VReplicationExec + +``` +VReplicationExec -- [--json] +``` + +### Backup + +Stops mysqld and uses the [BackupEngine](../../../../user-guides/operating-vitess/backup-and-restore/backup-and-restore/#backup-engines) to generate a new backup and uses the [BackupStorage](../../../../user-guides/operating-vitess/backup-and-restore/backup-and-restore/#backup-storage-services) service to store the results. This function also remembers if the tablet was replicating so that it can restore the same state after the backup completes. + +#### Example + +
Backup -- [--concurrency=4] [--upgrade-safe=false] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | Specifies the number of compression/checksum jobs to run simultaneously | +| upgrade-safe | Boolean | Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades | + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <Backup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. + +### RestoreFromBackup + +Stops mysqld and restores the data from the latest backup. + +#### Example + +
RestoreFromBackup -- [--backup_timestamp=2021-09-24.021828] <tablet alias>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| backup_timestamp | String | Use the latest backup at or before this time -- in `yyyy-MM-dd.HHmmss` format -- rather than using the most recent backup (Vitess 12.0+) | + +#### Errors + +* the <RestoreFromBackup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. + + +### ReparentTablet + +Reparent a tablet to the current primary in the shard. This only works if the current replication position matches the last known reparent action. + +#### Example + +
ReparentTablet <tablet alias>
+ +#### Errors + +* action <ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/throttler.md b/content/en/docs/19.0/reference/programs/vtctl/throttler.md new file mode 100644 index 000000000..49cd192d9 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/throttler.md @@ -0,0 +1,52 @@ +--- +title: vtctl Throttler Command Reference +series: vtctl +docs_nav_title: Throttler +--- + +The following `vtctl` commands are available for controlling the tablet throttler + +## Commands + +### UpdateThrottlerConfig + +Update tablet throttler configuration for all tablets of a given keyspace. + +#### Usage + +
UpdateThrottlerConfig -- [--enable|--disable] [--threshold=<float64>] [--custom-query=<query>] [--check-as-check-self|--check-as-check-shard] [--throttle-app|unthrottle-app=<name>] [--throttle-app-ratio=<float, range [0..1]>] [--throttle-app-duration=<duration>] <keyspace>
+ +#### Examples + +```UpdateThrottlerConfig -- --enable --threshold "3.0" commerce``` + +```UpdateThrottlerConfig -- --disable commerce``` + +```UpdateThrottlerConfig -- --throttle-app="vreplication" --throttle-app-ratio=0.5 --throttle-app-duration="30m" commerce``` + +```UpdateThrottlerConfig -- --unthrottle-app="vreplication" commerce``` + + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| `enable` | Boolean | enable the throttler. Once enabled, the throttler probes the MySQL servers for metrics, and responds to `check` requests according to those metrics | +| `disable` | Boolean | disables the throttler. Once disabled, the throttler responds to all `check` requests with `200 OK`. It will not probe the MySQL servers for metrics | +| `threshold` | Double | set a new threshold. Unless specified otherwise, the throttler measures replication lag by querying for heartbeat values, and the threshold stands for _seconds_ of lag (i.e. the value `2.5` stands for two and a half seconds) | +| `custom-query` | String | override the default replication lag measurement, and suggest a different query. Valid values are:
- _empty_, meaning the throttler should use the default replication lag query
- A `SELECT` that returns a single line, single column, floating point value
- A `SHOW GLOBAL STATUS|VARIABLES LIKE '...'`, for example `show global status like 'threads_running'` | +| `check-as-check-shard` | Boolean | this is the default behavior. A `/throttler/check` request checks the shard health. When using the default replication lag query, this is the desired check: the primary tablet's throttler responds by evaluating the overall lag throughout the shard/replicas | +| `check-as-check-self` | Boolean | override default behavior, and this can be useful when a `--custom-query` is set. A `/throttler/check` request will only consider the tablet's own metrics, and not the overall shard metrics | + + +#### Arguments + +* <keyspace> – Required. The keyspace for which to apply the throttler configuration. All tablets in all shards and cells assigned to this keyspace are affected. + +#### Errors + +Any error transporting the configuration to a cell's local topo server. + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctl/topo.md b/content/en/docs/19.0/reference/programs/vtctl/topo.md new file mode 100644 index 000000000..b6f8a69c4 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctl/topo.md @@ -0,0 +1,69 @@ +--- +title: vtctl Topo Command Reference +series: vtctl +docs_nav_title: Topology Service +--- + +The following `vtctl` commands are available for administering Topology Services. + +## Commands + +### TopoCat + +Retrieves the file(s) at <path> from the topo service, and displays it. It can resolve wildcards, and decode the proto-encoded data. + +#### Example + +
TopoCat -- [--cell <cell>] [--decode_proto] [--long] <path> [<path>...]
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- |:----------------------------------------------------------------| +| cell | string | topology cell to cat the file from. Defaults to global cell. | +| decode_proto | Boolean | decode proto files and display them as text. Defaults to false. | +| decode_proto_json | Boolean | decode proto files and display them as json. Defaults to false. | +| long | Boolean | long listing. Defaults to false. | + + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <path> – Required. +* <path>. – Optional. + +#### Errors + +* <TopoCat>: no path specified. This error occurs if the command is not called with at least one argument. +* <TopoCat>: invalid wildcards. If you send paths that don't contain any wildcard and don't exist. +* <TopoCat>: some paths had errors. If there is an error getting node data for given paths. + +### TopoCp + +Copy data at given path from topo service to local file or vice versa. + +#### Example + +
TopoCp -- [--cell <cell>] [--to_topo] <src> <dst>
+ +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- |:------------------------------------------------| +| cell | string | topology cell to use for the copy. Defaults to global cell. | +| to_topo | Boolean | copies from local server to topo instead (reverse direction). Defaults to false. | + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <src> – Required. Source from which data needs to be copied. It can be local file or some path in topo service, depedning on if `to_topo` is specified. +* <dst>. – Required. Destination to which data will be copied. It can be local file or some path in topo service, depedning on if `to_topo` is specified. + +#### Errors + +* <TopoCp>: need source and destination. This error occurs if the command is not called with proper `src` and `dst`. + + +## See Also + +* [vtctl command index](../../vtctl) diff --git a/content/en/docs/19.0/reference/programs/vtctld/_index.md b/content/en/docs/19.0/reference/programs/vtctld/_index.md new file mode 100644 index 000000000..3cbf33994 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctld/_index.md @@ -0,0 +1,192 @@ +--- +title: vtctld +series: vtctld +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtctld + +The Vitess cluster management daemon. + +### Synopsis + +vtctld provides web and gRPC interfaces to manage a single Vitess cluster. +It is usually the first Vitess component to be started after a valid global topology service has been created. + +For the last several releases, vtctld has been transitioning to a newer gRPC service for well-typed cluster management requests. +This is **required** to use programs such as vtadmin and vtctldclient, and The old API and service are deprecated and will be removed in a future release. +To enable this newer service, include "grpc-vtctld" in the --service_map argument. +This is demonstrated in the example usage below. + +``` +vtctld [flags] +``` + +### Examples + +``` +vtctld \ + --topo_implementation etcd2 \ + --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/ \ + --service_map 'grpc-vtctl,grpc-vtctld' \ + --backup_storage_implementation file \ + --file_backup_storage_root $VTDATAROOT/backups \ + --port 15000 \ + --grpc_port 15999 +``` + +### Options + +``` + --action_timeout duration time to wait for an action before resorting to force (default 1m0s) + --alsologtostderr log to standard error as well as files + --azblob_backup_account_key_file string Path to a file containing the Azure Storage account key; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_KEY will be used as the key itself (NOT a file path). + --azblob_backup_account_name string Azure Storage Account name for backups; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_NAME will be used. + --azblob_backup_buffer_size int The memory buffer size to use in bytes, per file or stripe, when streaming to Azure Blob Service. (default 104857600) + --azblob_backup_container_name string Azure Blob Container Name. + --azblob_backup_parallelism int Azure Blob operation parallelism (requires extra memory when increased -- a multiple of azblob_backup_buffer_size). (default 1) + --azblob_backup_storage_root string Root prefix for all backup-related Azure Blobs; this should exclude both initial and trailing '/' (e.g. just 'a/b' not '/a/b/'). + --backup_engine_implementation string Specifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin") + --backup_storage_block_size int if backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000) + --backup_storage_compress if set, the backup files will be compressed. (default true) + --backup_storage_implementation string Which backup storage implementation to use for creating and restoring backups. + --backup_storage_number_blocks int if backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, in parallel, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression. (default 2) + --builtinbackup-file-read-buffer-size uint read files using an IO buffer of this many bytes. Golang defaults are used when set to 0. + --builtinbackup-file-write-buffer-size uint write files using an IO buffer of this many bytes. Golang defaults are used when set to 0. (default 2097152) + --builtinbackup_mysqld_timeout duration how long to wait for mysqld to shutdown at the start of the backup. (default 10m0s) + --builtinbackup_progress duration how often to send progress updates when backing up large files. (default 5s) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --cell string cell to use + --ceph_backup_storage_config string Path to JSON config file for ceph backup storage. (default "ceph_backup_config.json") + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consul_auth_static_file string JSON File to read the topos/tokens from. + --datadog-agent-host string host to send spans to. if empty, no tracing will be done + --datadog-agent-port string port to send spans to. if empty, no tracing will be done + --disable_active_reparents if set, do not allow active reparents. Use this to protect a cluster using external reparents. + --emit_stats If set, emit stats to push-based monitoring and stats backends + --file_backup_storage_root string Root directory for the file backup storage. + --gcs_backup_storage_bucket string Google Cloud Storage bucket to use for backups. + --gcs_backup_storage_root string Root prefix for all backup-related object names. + --grpc_auth_mode string Which auth plugin implementation to use (eg: static) + --grpc_auth_mtls_allowed_substrings string List of substrings of at least one of the client certificate names (separated by colon). + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_auth_static_password_file string JSON File to read the users/passwords from. + --grpc_ca string server CA to use for gRPC connections, requires TLS, and enforces client certificate check + --grpc_cert string server certificate to use for gRPC connections, requires grpc_key, enables TLS + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_crl string path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake + --grpc_enable_optional_tls enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_key string server private key to use for gRPC connections, requires grpc_cert, enables TLS + --grpc_max_connection_age duration Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) + --grpc_max_connection_age_grace duration Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_port int Port to listen on for gRPC calls. If zero, do not listen. + --grpc_prometheus Enable gRPC monitoring with Prometheus. + --grpc_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --grpc_server_initial_conn_window_size int gRPC server initial connection window size + --grpc_server_initial_window_size int gRPC server initial window size + --grpc_server_keepalive_enforcement_policy_min_time duration gRPC server minimum keepalive time (default 10s) + --grpc_server_keepalive_enforcement_policy_permit_without_stream gRPC server permit client keepalive pings even when there are no active streams (RPCs) + -h, --help help for vtctld + --jaeger-agent-host string host and port to send spans to. if empty, no tracing will be done + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --lock-timeout duration Maximum time for which a shard/keyspace lock can be acquired for (default 45s) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --opentsdb_uri string URI of opentsdb /api/put method + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --port int port for the server + --pprof strings enable profiling + --proxy_tablets Setting this true will make vtctld proxy the tablet status instead of redirecting to them + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --remote_operation_timeout duration time to wait for a remote operation (default 15s) + --s3_backup_aws_endpoint string endpoint of the S3 backend (region must be provided). + --s3_backup_aws_region string AWS region to use. (default "us-east-1") + --s3_backup_aws_retries int AWS request retries. (default -1) + --s3_backup_force_path_style force the s3 path style. + --s3_backup_log_level string determine the S3 loglevel to use from LogOff, LogDebug, LogDebugWithSigning, LogDebugWithHTTPBody, LogDebugWithRequestRetries, LogDebugWithRequestErrors. (default "LogOff") + --s3_backup_server_side_encryption string server-side encryption algorithm (e.g., AES256, aws:kms, sse_c:/path/to/key/file). + --s3_backup_storage_bucket string S3 bucket to use for backups. + --s3_backup_storage_root string root prefix for all backup-related object names. + --s3_backup_tls_skip_verify_cert skip the 'certificate is valid' check for SSL connections. + --schema_change_check_interval duration How often the schema change dir is checked for schema changes. This value must be positive; if zero or lower, the default of 1m is used. (default 1m0s) + --schema_change_controller string Schema change controller is responsible for finding schema changes and responding to schema change events. + --schema_change_dir string Directory containing schema changes for all keyspaces. Each keyspace has its own directory, and schema changes are expected to live in '$KEYSPACE/input' dir. (e.g. 'test_keyspace/input/*sql'). Each sql file represents a schema change. + --schema_change_replicas_timeout duration How long to wait for replicas to receive a schema change. (default 10s) + --schema_change_user string The user who schema changes are submitted on behalf of. + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --sql-max-length-errors int truncate queries in error logs to the given length (default unlimited) + --sql-max-length-ui int truncate queries in debug UIs to the given length (default 512) (default 512) + --stats_backend string The name of the registered push-based monitoring/stats backend to use + --stats_combine_dimensions string List of dimensions to be combined into a single "all" value in exported stats vars + --stats_common_tags strings Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 + --stats_drop_variables string Variables to be dropped from the list of exported variables. + --stats_emit_period duration Interval between emitting stats to all registered backends (default 1m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_grpc_ca string the server ca to use to validate servers when connecting + --tablet_grpc_cert string the cert to use to connect + --tablet_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_grpc_key string the key to use to connect + --tablet_grpc_server_name string the server name to use to validate server certificate + --tablet_health_keep_alive duration close streaming tablet health connection if there are no requests for this long (default 5m0s) + --tablet_manager_grpc_ca string the server ca to use to validate servers when connecting + --tablet_manager_grpc_cert string the cert to use to connect + --tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) + --tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100) + --tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_manager_grpc_key string the key to use to connect + --tablet_manager_grpc_server_name string the server name to use to validate server certificate + --tablet_manager_protocol string Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") + --tablet_protocol string Protocol to use to make queryservice RPCs to vttablets. (default "grpc") + --tablet_refresh_interval duration Tablet refresh interval. (default 1m0s) + --tablet_refresh_known_tablets Whether to reload the tablet's address/port map from topo in case they change. (default true) + --tablet_url_template string Format string describing debug tablet url formatting. See getTabletDebugURL() for how to customize this. (default "http://{{.GetTabletHostPort}}") + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) + --topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server + --topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS + --topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS + --topo_global_root string the path of the global topology data in the global topology server + --topo_global_server_address string the address of the global topology server + --topo_implementation string the topology implementation to use + --topo_read_concurrency int Concurrency of topo reads. (default 32) + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --tracer string tracing service to use (default "noop") + --tracing-enable-logging whether to enable logging in the tracing service + --tracing-sampling-rate float sampling rate for the probabilistic jaeger sampler (default 0.1) + --tracing-sampling-type string sampling strategy to use for jaeger. possible values are 'const', 'probabilistic', 'rateLimiting', or 'remote' (default "const") + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --vtctld_sanitize_log_messages When true, vtctld sanitizes logging. +``` + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/_index.md b/content/en/docs/19.0/reference/programs/vtctldclient/_index.md new file mode 100644 index 000000000..59a7cbc77 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/_index.md @@ -0,0 +1,111 @@ +--- +title: vtctldclient +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient + +Executes a cluster management command on the remote vtctld server. + +``` +vtctldclient [flags] +``` + +### Options + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -h, --help help for vtctldclient + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient AddCellInfo](./vtctldclient_addcellinfo/) - Registers a local topology service in a new cell by creating the CellInfo. +* [vtctldclient AddCellsAlias](./vtctldclient_addcellsalias/) - Defines a group of cells that can be referenced by a single name (the alias). +* [vtctldclient ApplyRoutingRules](./vtctldclient_applyroutingrules/) - Applies the VSchema routing rules. +* [vtctldclient ApplySchema](./vtctldclient_applyschema/) - Applies the schema change to the specified keyspace on every primary, running in parallel on all shards. The changes are then propagated to replicas via replication. +* [vtctldclient ApplyShardRoutingRules](./vtctldclient_applyshardroutingrules/) - Applies the provided shard routing rules. +* [vtctldclient ApplyVSchema](./vtctldclient_applyvschema/) - Applies the VTGate routing schema to the provided keyspace. Shows the result after application. +* [vtctldclient Backup](./vtctldclient_backup/) - Uses the BackupStorage service on the given tablet to create and store a new backup. +* [vtctldclient BackupShard](./vtctldclient_backupshard/) - Finds the most up-to-date REPLICA, RDONLY, or SPARE tablet in the given shard and uses the BackupStorage service on that tablet to create and store a new backup. +* [vtctldclient ChangeTabletType](./vtctldclient_changetablettype/) - Changes the db type for the specified tablet, if possible. +* [vtctldclient CreateKeyspace](./vtctldclient_createkeyspace/) - Creates the specified keyspace in the topology. +* [vtctldclient CreateShard](./vtctldclient_createshard/) - Creates the specified shard in the topology. +* [vtctldclient DeleteCellInfo](./vtctldclient_deletecellinfo/) - Deletes the CellInfo for the provided cell. +* [vtctldclient DeleteCellsAlias](./vtctldclient_deletecellsalias/) - Deletes the CellsAlias for the provided alias. +* [vtctldclient DeleteKeyspace](./vtctldclient_deletekeyspace/) - Deletes the specified keyspace from the topology. +* [vtctldclient DeleteShards](./vtctldclient_deleteshards/) - Deletes the specified shards from the topology. +* [vtctldclient DeleteSrvVSchema](./vtctldclient_deletesrvvschema/) - Deletes the SrvVSchema object in the given cell. +* [vtctldclient DeleteTablets](./vtctldclient_deletetablets/) - Deletes tablet(s) from the topology. +* [vtctldclient EmergencyReparentShard](./vtctldclient_emergencyreparentshard/) - Reparents the shard to the new primary. Assumes the old primary is dead and not responding. +* [vtctldclient ExecuteFetchAsApp](./vtctldclient_executefetchasapp/) - Executes the given query as the App user on the remote tablet. +* [vtctldclient ExecuteFetchAsDBA](./vtctldclient_executefetchasdba/) - Executes the given query as the DBA user on the remote tablet. +* [vtctldclient ExecuteHook](./vtctldclient_executehook/) - Runs the specified hook on the given tablet. +* [vtctldclient FindAllShardsInKeyspace](./vtctldclient_findallshardsinkeyspace/) - Returns a map of shard names to shard references for a given keyspace. +* [vtctldclient GenerateShardRanges](./vtctldclient_generateshardranges/) - Print a set of shard ranges assuming a keyspace with N shards. +* [vtctldclient GetBackups](./vtctldclient_getbackups/) - Lists backups for the given shard. +* [vtctldclient GetCellInfo](./vtctldclient_getcellinfo/) - Gets the CellInfo object for the given cell. +* [vtctldclient GetCellInfoNames](./vtctldclient_getcellinfonames/) - Lists the names of all cells in the cluster. +* [vtctldclient GetCellsAliases](./vtctldclient_getcellsaliases/) - Gets all CellsAlias objects in the cluster. +* [vtctldclient GetFullStatus](./vtctldclient_getfullstatus/) - Outputs a JSON structure that contains full status of MySQL including the replication information, semi-sync information, GTID information among others. +* [vtctldclient GetKeyspace](./vtctldclient_getkeyspace/) - Returns information about the given keyspace from the topology. +* [vtctldclient GetKeyspaces](./vtctldclient_getkeyspaces/) - Returns information about every keyspace in the topology. +* [vtctldclient GetPermissions](./vtctldclient_getpermissions/) - Displays the permissions for a tablet. +* [vtctldclient GetRoutingRules](./vtctldclient_getroutingrules/) - Displays the VSchema routing rules. +* [vtctldclient GetSchema](./vtctldclient_getschema/) - Displays the full schema for a tablet, optionally restricted to the specified tables/views. +* [vtctldclient GetShard](./vtctldclient_getshard/) - Returns information about a shard in the topology. +* [vtctldclient GetShardRoutingRules](./vtctldclient_getshardroutingrules/) - Displays the currently active shard routing rules as a JSON document. +* [vtctldclient GetSrvKeyspaceNames](./vtctldclient_getsrvkeyspacenames/) - Outputs a JSON mapping of cell=>keyspace names served in that cell. Omit to query all cells. +* [vtctldclient GetSrvKeyspaces](./vtctldclient_getsrvkeyspaces/) - Returns the SrvKeyspaces for the given keyspace in one or more cells. +* [vtctldclient GetSrvVSchema](./vtctldclient_getsrvvschema/) - Returns the SrvVSchema for the given cell. +* [vtctldclient GetSrvVSchemas](./vtctldclient_getsrvvschemas/) - Returns the SrvVSchema for all cells, optionally filtered by the given cells. +* [vtctldclient GetTablet](./vtctldclient_gettablet/) - Outputs a JSON structure that contains information about the tablet. +* [vtctldclient GetTabletVersion](./vtctldclient_gettabletversion/) - Print the version of a tablet from its debug vars. +* [vtctldclient GetTablets](./vtctldclient_gettablets/) - Looks up tablets according to filter criteria. +* [vtctldclient GetTopologyPath](./vtctldclient_gettopologypath/) - Gets the value associated with the particular path (key) in the topology server. +* [vtctldclient GetVSchema](./vtctldclient_getvschema/) - Prints a JSON representation of a keyspace's topo record. +* [vtctldclient GetWorkflows](./vtctldclient_getworkflows/) - Gets all vreplication workflows (Reshard, MoveTables, etc) in the given keyspace. +* [vtctldclient LegacyVtctlCommand](./vtctldclient_legacyvtctlcommand/) - Invoke a legacy vtctlclient command. Flag parsing is best effort. +* [vtctldclient MoveTables](./vtctldclient_movetables/) - Perform commands related to moving tables from a source keyspace to a target keyspace. +* [vtctldclient OnlineDDL](./vtctldclient_onlineddl/) - Operates on online DDL (schema migrations). +* [vtctldclient PingTablet](./vtctldclient_pingtablet/) - Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations. +* [vtctldclient PlannedReparentShard](./vtctldclient_plannedreparentshard/) - Reparents the shard to a new primary, or away from an old primary. Both the old and new primaries must be up and running. +* [vtctldclient RebuildKeyspaceGraph](./vtctldclient_rebuildkeyspacegraph/) - Rebuilds the serving data for the keyspace(s). This command may trigger an update to all connected clients. +* [vtctldclient RebuildVSchemaGraph](./vtctldclient_rebuildvschemagraph/) - Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided). +* [vtctldclient RefreshState](./vtctldclient_refreshstate/) - Reloads the tablet record on the specified tablet. +* [vtctldclient RefreshStateByShard](./vtctldclient_refreshstatebyshard/) - Reloads the tablet record all tablets in the shard, optionally limited to the specified cells. +* [vtctldclient ReloadSchema](./vtctldclient_reloadschema/) - Reloads the schema on a remote tablet. +* [vtctldclient ReloadSchemaKeyspace](./vtctldclient_reloadschemakeyspace/) - Reloads the schema on all tablets in a keyspace. This is done on a best-effort basis. +* [vtctldclient ReloadSchemaShard](./vtctldclient_reloadschemashard/) - Reloads the schema on all tablets in a shard. This is done on a best-effort basis. +* [vtctldclient RemoveBackup](./vtctldclient_removebackup/) - Removes the given backup from the BackupStorage used by vtctld. +* [vtctldclient RemoveKeyspaceCell](./vtctldclient_removekeyspacecell/) - Removes the specified cell from the Cells list for all shards in the specified keyspace (by calling RemoveShardCell on every shard). It also removes the SrvKeyspace for that keyspace in that cell. +* [vtctldclient RemoveShardCell](./vtctldclient_removeshardcell/) - Remove the specified cell from the specified shard's Cells list. +* [vtctldclient ReparentTablet](./vtctldclient_reparenttablet/) - Reparent a tablet to the current primary in the shard. +* [vtctldclient Reshard](./vtctldclient_reshard/) - Perform commands related to resharding a keyspace. +* [vtctldclient RestoreFromBackup](./vtctldclient_restorefrombackup/) - Stops mysqld on the specified tablet and restores the data from either the latest backup or closest before `backup-timestamp`. +* [vtctldclient RunHealthCheck](./vtctldclient_runhealthcheck/) - Runs a healthcheck on the remote tablet. +* [vtctldclient SetKeyspaceDurabilityPolicy](./vtctldclient_setkeyspacedurabilitypolicy/) - Sets the durability-policy used by the specified keyspace. +* [vtctldclient SetShardIsPrimaryServing](./vtctldclient_setshardisprimaryserving/) - Add or remove a shard from serving. This is meant as an emergency function. It does not rebuild any serving graphs; i.e. it does not run `RebuildKeyspaceGraph`. +* [vtctldclient SetShardTabletControl](./vtctldclient_setshardtabletcontrol/) - Sets the TabletControl record for a shard and tablet type. Only use this for an emergency fix or after a finished MoveTables. +* [vtctldclient SetWritable](./vtctldclient_setwritable/) - Sets the specified tablet as writable or read-only. +* [vtctldclient ShardReplicationFix](./vtctldclient_shardreplicationfix/) - Walks through a ShardReplication object and fixes the first error encountered. +* [vtctldclient ShardReplicationPositions](./vtctldclient_shardreplicationpositions/) - +* [vtctldclient SleepTablet](./vtctldclient_sleeptablet/) - Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing. +* [vtctldclient SourceShardAdd](./vtctldclient_sourceshardadd/) - Adds the SourceShard record with the provided index for emergencies only. It does not call RefreshState for the shard primary. +* [vtctldclient SourceShardDelete](./vtctldclient_sourcesharddelete/) - Deletes the SourceShard record with the provided index. This should only be used for emergency cleanup. It does not call RefreshState for the shard primary. +* [vtctldclient StartReplication](./vtctldclient_startreplication/) - Starts replication on the specified tablet. +* [vtctldclient StopReplication](./vtctldclient_stopreplication/) - Stops replication on the specified tablet. +* [vtctldclient TabletExternallyReparented](./vtctldclient_tabletexternallyreparented/) - Updates the topology record for the tablet's shard to acknowledge that an external tool made this tablet the primary. +* [vtctldclient UpdateCellInfo](./vtctldclient_updatecellinfo/) - Updates the content of a CellInfo with the provided parameters, creating the CellInfo if it does not exist. +* [vtctldclient UpdateCellsAlias](./vtctldclient_updatecellsalias/) - Updates the content of a CellsAlias with the provided parameters, creating the CellsAlias if it does not exist. +* [vtctldclient UpdateThrottlerConfig](./vtctldclient_updatethrottlerconfig/) - Update the tablet throttler configuration for all tablets in the given keyspace (across all cells) +* [vtctldclient VDiff](./vtctldclient_vdiff/) - Perform commands related to diffing tables involved in a VReplication workflow between the source and target. +* [vtctldclient Validate](./vtctldclient_validate/) - Validates that all nodes reachable from the global replication graph, as well as all tablets in discoverable cells, are consistent. +* [vtctldclient ValidateKeyspace](./vtctldclient_validatekeyspace/) - Validates that all nodes reachable from the specified keyspace are consistent. +* [vtctldclient ValidateSchemaKeyspace](./vtctldclient_validateschemakeyspace/) - Validates that the schema on the primary tablet for shard 0 matches the schema on all other tablets in the keyspace. +* [vtctldclient ValidateShard](./vtctldclient_validateshard/) - Validates that all nodes reachable from the specified shard are consistent. +* [vtctldclient ValidateVersionKeyspace](./vtctldclient_validateversionkeyspace/) - Validates that the version on the primary tablet of shard 0 matches all of the other tablets in the keyspace. +* [vtctldclient ValidateVersionShard](./vtctldclient_validateversionshard/) - Validates that the version on the primary matches all of the replicas. +* [vtctldclient Workflow](./vtctldclient_workflow/) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_AddCellInfo.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_AddCellInfo.md new file mode 100644 index 000000000..c616a5f81 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_AddCellInfo.md @@ -0,0 +1,39 @@ +--- +title: AddCellInfo +series: vtctldclient +--- +## vtctldclient AddCellInfo + +Registers a local topology service in a new cell by creating the CellInfo. + +### Synopsis + +Registers a local topology service in a new cell by creating the CellInfo +with the provided parameters. + +The address will be used to connect to the topology service, and Vitess data will +be stored starting at the provided root. + +``` +vtctldclient AddCellInfo --root [--server-address ] +``` + +### Options + +``` + -h, --help help for AddCellInfo + -r, --root string The root path the topology server will use for this cell. + -a, --server-address string The address the topology server will connect to for this cell. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_AddCellsAlias.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_AddCellsAlias.md new file mode 100644 index 000000000..c900a8acf --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_AddCellsAlias.md @@ -0,0 +1,38 @@ +--- +title: AddCellsAlias +series: vtctldclient +--- +## vtctldclient AddCellsAlias + +Defines a group of cells that can be referenced by a single name (the alias). + +### Synopsis + +Defines a group of cells that can be referenced by a single name (the alias). + +When routing query traffic, replica/rdonly traffic can be routed across cells +within the group (alias). Only primary traffic can be routed across cells not in +the same group (alias). + +``` +vtctldclient AddCellsAlias --cells [--cells ...] +``` + +### Options + +``` + -c, --cells strings The list of cell names that are members of this alias. + -h, --help help for AddCellsAlias +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyRoutingRules.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyRoutingRules.md new file mode 100644 index 000000000..6e52c7d3d --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyRoutingRules.md @@ -0,0 +1,34 @@ +--- +title: ApplyRoutingRules +series: vtctldclient +--- +## vtctldclient ApplyRoutingRules + +Applies the VSchema routing rules. + +``` +vtctldclient ApplyRoutingRules {--rules RULES | --rules-file RULES_FILE} [--cells=c1,c2,...] [--skip-rebuild] [--dry-run] +``` + +### Options + +``` + -c, --cells strings Limit the VSchema graph rebuildingg to the specified cells. Ignored if --skip-rebuild is specified. + -d, --dry-run Load the specified routing rules as a validation step, but do not actually apply the rules to the topo. + -h, --help help for ApplyRoutingRules + -r, --rules string Routing rules, specified as a string. + -f, --rules-file string Path to a file containing routing rules specified as JSON. + --skip-rebuild Skip rebuilding the SrvVSchema objects. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplySchema.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplySchema.md new file mode 100644 index 000000000..abd1153e9 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplySchema.md @@ -0,0 +1,55 @@ +--- +title: ApplySchema +series: vtctldclient +commit: b2d7604e4e0728329314500c182c3192cee74510 +--- +## vtctldclient ApplySchema + +Applies the schema change to the specified keyspace on every primary, running in parallel on all shards. The changes are then propagated to replicas via replication. + +### Synopsis + +Applies the schema change to the specified keyspace on every primary, running in parallel on all shards. The changes are then propagated to replicas via replication. + +If --allow-long-unavailability is set, schema changes affecting a large number of rows (and possibly incurring a longer period of unavailability) will not be rejected. +--ddl-strategy is used to instruct migrations via vreplication, gh-ost or pt-osc with optional parameters. +--migration-context allows the user to specify a custom migration context for online DDL migrations. +If --skip-preflight, SQL goes directly to shards without going through sanity checks. + +The --uuid and --sql flags are repeatable, so they can be passed multiple times to build a list of values. +For --uuid, this is used like "--uuid $first_uuid --uuid $second_uuid". +For --sql, semi-colons and repeated values may be mixed, for example: + + ApplySchema --sql "CREATE TABLE my_table; CREATE TABLE my_other_table" + ApplySchema --sql "CREATE TABLE my_table" --sql "CREATE TABLE my_other_table" + +``` +vtctldclient ApplySchema [--ddl-strategy ] [--uuid ...] [--migration-context ] [--wait-replicas-timeout ] [--caller-id ] {--sql-file | --sql } +``` + +### Options + +``` + --allow-long-unavailability Deprecated and has no effect. + --batch-size int How many queries to batch together. Only applicable when all queries are CREATE TABLE|VIEW + --caller-id string Effective caller ID used for the operation and should map to an ACL name which grants this identity the necessary permissions to perform the operation (this is only necessary when strict table ACLs are used). + --ddl-strategy string Online DDL strategy, compatible with @@ddl_strategy session variable (examples: 'gh-ost', 'pt-osc', 'gh-ost --max-load=Threads_running=100'. (default "direct") + -h, --help help for ApplySchema + --migration-context string For Online DDL, optionally supply a custom unique string used as context for the migration(s) in this command. By default a unique context is auto-generated by Vitess. + --sql stringArray Semicolon-delimited, repeatable SQL commands to apply. Exactly one of --sql|--sql-file is required. + --sql-file string Path to a file containing semicolon-delimited SQL commands to apply. Exactly one of --sql|--sql-file is required. + --uuid strings Optional, comma-delimited, repeatable, explicit UUIDs for migration. If given, must match number of DDL changes. + --wait-replicas-timeout duration Amount of time to wait for replicas to receive the schema change via replication. (default 10s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyShardRoutingRules.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyShardRoutingRules.md new file mode 100644 index 000000000..76e6b9336 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyShardRoutingRules.md @@ -0,0 +1,34 @@ +--- +title: ApplyShardRoutingRules +series: vtctldclient +--- +## vtctldclient ApplyShardRoutingRules + +Applies the provided shard routing rules. + +``` +vtctldclient ApplyShardRoutingRules {--rules RULES | --rules-file RULES_FILE} [--cells=c1,c2,...] [--skip-rebuild] [--dry-run] +``` + +### Options + +``` + -c, --cells strings Limit the VSchema graph rebuilding to the specified cells. Ignored if --skip-rebuild is specified. + -d, --dry-run Validate the specified shard routing rules and note actions that would be taken, but do not actually apply the rules to the topo. + -h, --help help for ApplyShardRoutingRules + -r, --rules string Shard routing rules, specified as a string + -f, --rules-file string Path to a file containing shard routing rules specified as JSON + --skip-rebuild Skip rebuilding the SrvVSchema objects. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyVSchema.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyVSchema.md new file mode 100644 index 000000000..def2299a9 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ApplyVSchema.md @@ -0,0 +1,36 @@ +--- +title: ApplyVSchema +series: vtctldclient +--- +## vtctldclient ApplyVSchema + +Applies the VTGate routing schema to the provided keyspace. Shows the result after application. + +``` +vtctldclient ApplyVSchema {--vschema= || --vschema-file= || --sql= || --sql-file=} [--cells=c1,c2,...] [--skip-rebuild] [--dry-run] +``` + +### Options + +``` + --cells strings Limits the rebuild to the specified cells, after application. Ignored if --skip-rebuild is set. + --dry-run If set, do not save the altered vschema, simply echo to console. + -h, --help help for ApplyVSchema + --skip-rebuild Skip rebuilding the SrvSchema objects. + --sql alter table t add vindex hash(id) A VSchema DDL SQL statement, e.g. alter table t add vindex hash(id). + --sql-file string Path to a file containing a VSchema DDL SQL. + --vschema string VSchema to apply, in JSON form. + --vschema-file string Path to a file containing the vschema to apply, in JSON form. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Backup.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Backup.md new file mode 100644 index 000000000..7220aa66e --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Backup.md @@ -0,0 +1,33 @@ +--- +title: Backup +series: vtctldclient +--- +## vtctldclient Backup + +Uses the BackupStorage service on the given tablet to create and store a new backup. + +``` +vtctldclient Backup [--concurrency ] [--allow-primary] [--incremental-from-pos=|auto] [--upgrade-safe] +``` + +### Options + +``` + --allow-primary Allow the primary of a shard to be used for the backup. WARNING: If using the builtin backup engine, this will shutdown mysqld on the primary and stop writes for the duration of the backup. + --concurrency uint Specifies the number of compression/checksum jobs to run simultaneously. (default 4) + -h, --help help for Backup + --incremental-from-pos string Position of previous backup. Default: empty. If given, then this backup becomes an incremental backup from given position. If value is 'auto', backup taken from last successful backup position + --upgrade-safe Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_BackupShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_BackupShard.md new file mode 100644 index 000000000..35b785272 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_BackupShard.md @@ -0,0 +1,39 @@ +--- +title: BackupShard +series: vtctldclient +--- +## vtctldclient BackupShard + +Finds the most up-to-date REPLICA, RDONLY, or SPARE tablet in the given shard and uses the BackupStorage service on that tablet to create and store a new backup. + +### Synopsis + +Finds the most up-to-date REPLICA, RDONLY, or SPARE tablet in the given shard and uses the BackupStorage service on that tablet to create and store a new backup. + +If no replica-type tablet can be found, the backup can be taken on the primary if --allow-primary is specified. + +``` +vtctldclient BackupShard [--concurrency ] [--allow-primary] [--incremental-from-pos=|auto] [--upgrade-safe] +``` + +### Options + +``` + --allow-primary Allow the primary of a shard to be used for the backup. WARNING: If using the builtin backup engine, this will shutdown mysqld on the primary and stop writes for the duration of the backup. + --concurrency uint Specifies the number of compression/checksum jobs to run simultaneously. (default 4) + -h, --help help for BackupShard + --incremental-from-pos string Position of previous backup. Default: empty. If given, then this backup becomes an incremental backup from given position. If value is 'auto', backup taken from last successful backup position + --upgrade-safe Whether to use innodb_fast_shutdown=0 for the backup so it is safe to use for MySQL upgrades. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ChangeTabletType.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ChangeTabletType.md new file mode 100644 index 000000000..0c17b8e5c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ChangeTabletType.md @@ -0,0 +1,37 @@ +--- +title: ChangeTabletType +series: vtctldclient +--- +## vtctldclient ChangeTabletType + +Changes the db type for the specified tablet, if possible. + +### Synopsis + +Changes the db type for the specified tablet, if possible. + +This command is used primarily to arrange replicas, and it will not convert a primary. +NOTE: This command automatically updates the serving graph. + +``` +vtctldclient ChangeTabletType [--dry-run] +``` + +### Options + +``` + -d, --dry-run Shows the proposed change without actually executing it. + -h, --help help for ChangeTabletType +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_CreateKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_CreateKeyspace.md new file mode 100644 index 000000000..bacc1522a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_CreateKeyspace.md @@ -0,0 +1,44 @@ +--- +title: CreateKeyspace +series: vtctldclient +--- +## vtctldclient CreateKeyspace + +Creates the specified keyspace in the topology. + +### Synopsis + +Creates the specified keyspace in the topology. + +For a SNAPSHOT keyspace, the request must specify the name of a base keyspace, +as well as a snapshot time. + +``` +vtctldclient CreateKeyspace [--force|-f] [--type KEYSPACE_TYPE] [--base-keyspace KEYSPACE --snapshot-timestamp TIME] [--served-from DB_TYPE:KEYSPACE ...] [--durability-policy ] [--sidecar-db-name ] +``` + +### Options + +``` + -e, --allow-empty-vschema Allows a new keyspace to have no vschema. + --base-keyspace string The base keyspace for a snapshot keyspace. + --durability-policy string Type of durability to enforce for this keyspace. Default is none. Possible values include 'semi_sync' and others as dictated by registered plugins. (default "none") + -f, --force Proceeds even if the keyspace already exists. Does not overwrite the existing keyspace record. + -h, --help help for CreateKeyspace + --served-from cli.StringMapValue Specifies a set of db_type:keyspace pairs used to serve traffic for the keyspace. + --sidecar-db-name string (Experimental) Name of the Vitess sidecar database that tablets in this keyspace will use for internal metadata. (default "_vt") + --snapshot-timestamp string The snapshot time for a snapshot keyspace, as a timestamp in RFC3339 format. + --type cli.KeyspaceTypeFlag The type of the keyspace. (default NORMAL) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_CreateShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_CreateShard.md new file mode 100644 index 000000000..8e2ce00ba --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_CreateShard.md @@ -0,0 +1,31 @@ +--- +title: CreateShard +series: vtctldclient +--- +## vtctldclient CreateShard + +Creates the specified shard in the topology. + +``` +vtctldclient CreateShard [--force|-f] [--include-parent|-p] +``` + +### Options + +``` + -f, --force Overwrite an existing shard record, if one exists. + -h, --help help for CreateShard + -p, --include-parent Creates the parent keyspace record if does not already exist. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteCellInfo.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteCellInfo.md new file mode 100644 index 000000000..382ad745c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteCellInfo.md @@ -0,0 +1,34 @@ +--- +title: DeleteCellInfo +series: vtctldclient +--- +## vtctldclient DeleteCellInfo + +Deletes the CellInfo for the provided cell. + +### Synopsis + +Deletes the CellInfo for the provided cell. The cell cannot be referenced by any Shard record. + +``` +vtctldclient DeleteCellInfo [--force] +``` + +### Options + +``` + -f, --force Proceeds even if the cell's topology server cannot be reached. The assumption is that you shut down the entire cell, and just need to update the global topo data. + -h, --help help for DeleteCellInfo +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteCellsAlias.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteCellsAlias.md new file mode 100644 index 000000000..8ef4c36e1 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteCellsAlias.md @@ -0,0 +1,33 @@ +--- +title: DeleteCellsAlias +series: vtctldclient +--- +## vtctldclient DeleteCellsAlias + +Deletes the CellsAlias for the provided alias. + +### Synopsis + +Deletes the CellsAlias for the provided alias. + +``` +vtctldclient DeleteCellsAlias +``` + +### Options + +``` + -h, --help help for DeleteCellsAlias +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteKeyspace.md new file mode 100644 index 000000000..d311ebc55 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteKeyspace.md @@ -0,0 +1,38 @@ +--- +title: DeleteKeyspace +series: vtctldclient +--- +## vtctldclient DeleteKeyspace + +Deletes the specified keyspace from the topology. + +### Synopsis + +Deletes the specified keyspace from the topology. + +In recursive mode, it also recursively deletes all shards in the keyspace. +Otherwise, the keyspace must be empty (have no shards), or returns an error. + +``` +vtctldclient DeleteKeyspace [--recursive|-r] [--force|-f] +``` + +### Options + +``` + -f, --force Delete the keyspace even if it cannot be locked; this should only be used for cleanup operations. + -h, --help help for DeleteKeyspace + -r, --recursive Recursively delete all shards in the keyspace, and all tablets in those shards. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteShards.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteShards.md new file mode 100644 index 000000000..12ada3b13 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteShards.md @@ -0,0 +1,40 @@ +--- +title: DeleteShards +series: vtctldclient +--- +## vtctldclient DeleteShards + +Deletes the specified shards from the topology. + +### Synopsis + +Deletes the specified shards from the topology. + +In recursive mode, it also deletes all tablets belonging to the shard. +Otherwise, the shard must be empty (have no tablets) or returns an error for +that shard. + +``` +vtctldclient DeleteShards [--recursive|-r] [--even-if-serving] [--force|-f] [ ...] +``` + +### Options + +``` + --even-if-serving Remove the shard even if it is serving. Use with caution. + -f, --force Remove the shard even if it cannot be locked; this should only be used for cleanup operations. + -h, --help help for DeleteShards + -r, --recursive Also delete all tablets belonging to the shard. This is required to delete a non-empty shard. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteSrvVSchema.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteSrvVSchema.md new file mode 100644 index 000000000..76ae623fd --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteSrvVSchema.md @@ -0,0 +1,29 @@ +--- +title: DeleteSrvVSchema +series: vtctldclient +--- +## vtctldclient DeleteSrvVSchema + +Deletes the SrvVSchema object in the given cell. + +``` +vtctldclient DeleteSrvVSchema +``` + +### Options + +``` + -h, --help help for DeleteSrvVSchema +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteTablets.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteTablets.md new file mode 100644 index 000000000..edea4d04b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_DeleteTablets.md @@ -0,0 +1,30 @@ +--- +title: DeleteTablets +series: vtctldclient +--- +## vtctldclient DeleteTablets + +Deletes tablet(s) from the topology. + +``` +vtctldclient DeleteTablets [ ... ] +``` + +### Options + +``` + -p, --allow-primary Allow the primary tablet of a shard to be deleted. Use with caution. + -h, --help help for DeleteTablets +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_EmergencyReparentShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_EmergencyReparentShard.md new file mode 100644 index 000000000..1d3c043b3 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_EmergencyReparentShard.md @@ -0,0 +1,34 @@ +--- +title: EmergencyReparentShard +series: vtctldclient +--- +## vtctldclient EmergencyReparentShard + +Reparents the shard to the new primary. Assumes the old primary is dead and not responding. + +``` +vtctldclient EmergencyReparentShard +``` + +### Options + +``` + -h, --help help for EmergencyReparentShard + -i, --ignore-replicas strings Comma-separated, repeated list of replica tablet aliases to ignore during the emergency reparent. + --new-primary string Alias of a tablet that should be the new primary. If not specified, the vtctld will select the best candidate to promote. + --prevent-cross-cell-promotion Only promotes a new primary from the same cell as the previous primary. + --wait-for-all-tablets Should ERS wait for all the tablets to respond. Useful when all the tablets are reachable. + --wait-replicas-timeout duration Time to wait for replicas to catch up in reparenting. (default 15s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteFetchAsApp.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteFetchAsApp.md new file mode 100644 index 000000000..5c23d1efb --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteFetchAsApp.md @@ -0,0 +1,32 @@ +--- +title: ExecuteFetchAsApp +series: vtctldclient +--- +## vtctldclient ExecuteFetchAsApp + +Executes the given query as the App user on the remote tablet. + +``` +vtctldclient ExecuteFetchAsApp [--max-rows ] [--json|-j] [--use-pool] +``` + +### Options + +``` + -h, --help help for ExecuteFetchAsApp + -j, --json Output the results in JSON instead of a human-readable table. + --max-rows int The maximum number of rows to fetch from the remote tablet. (default 10000) + --use-pool Use the tablet connection pool instead of creating a fresh connection. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteFetchAsDBA.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteFetchAsDBA.md new file mode 100644 index 000000000..48a3fe4e5 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteFetchAsDBA.md @@ -0,0 +1,33 @@ +--- +title: ExecuteFetchAsDBA +series: vtctldclient +--- +## vtctldclient ExecuteFetchAsDBA + +Executes the given query as the DBA user on the remote tablet. + +``` +vtctldclient ExecuteFetchAsDBA [--max-rows ] [--json|-j] [--disable-binlogs] [--reload-schema] +``` + +### Options + +``` + --disable-binlogs Disables binary logging during the query. + -h, --help help for ExecuteFetchAsDBA + -j, --json Output the results in JSON instead of a human-readable table. + --max-rows int The maximum number of rows to fetch from the remote tablet. (default 10000) + --reload-schema Instructs the tablet to reload its schema after executing the query. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteHook.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteHook.md new file mode 100644 index 000000000..e9f26b40e --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ExecuteHook.md @@ -0,0 +1,43 @@ +--- +title: ExecuteHook +series: vtctldclient +--- +## vtctldclient ExecuteHook + +Runs the specified hook on the given tablet. + +### Synopsis + +Runs the specified hook on the given tablet. + +A hook is an executable script that resides in the ${VTROOT}/vthook directory. +For ExecuteHook, this is on the tablet requested, not on the vtctld or the host +running the vtctldclient. + +Any key-value pairs passed after the hook name will be passed as parameters to +the hook on the tablet. + +Note: hook names may not contain slash (/) characters. + + +``` +vtctldclient ExecuteHook [ ...] +``` + +### Options + +``` + -h, --help help for ExecuteHook +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_FindAllShardsInKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_FindAllShardsInKeyspace.md new file mode 100644 index 000000000..d794a61a6 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_FindAllShardsInKeyspace.md @@ -0,0 +1,29 @@ +--- +title: FindAllShardsInKeyspace +series: vtctldclient +--- +## vtctldclient FindAllShardsInKeyspace + +Returns a map of shard names to shard references for a given keyspace. + +``` +vtctldclient FindAllShardsInKeyspace +``` + +### Options + +``` + -h, --help help for FindAllShardsInKeyspace +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GenerateShardRanges.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GenerateShardRanges.md new file mode 100644 index 000000000..5f4f8421a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GenerateShardRanges.md @@ -0,0 +1,29 @@ +--- +title: GenerateShardRanges +series: vtctldclient +--- +## vtctldclient GenerateShardRanges + +Print a set of shard ranges assuming a keyspace with N shards. + +``` +vtctldclient GenerateShardRanges +``` + +### Options + +``` + -h, --help help for GenerateShardRanges +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetBackups.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetBackups.md new file mode 100644 index 000000000..15ce0af98 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetBackups.md @@ -0,0 +1,31 @@ +--- +title: GetBackups +series: vtctldclient +--- +## vtctldclient GetBackups + +Lists backups for the given shard. + +``` +vtctldclient GetBackups [--limit ] [--json] +``` + +### Options + +``` + -h, --help help for GetBackups + -j, --json Output backup info in JSON format rather than a list of backups. + -l, --limit uint32 Retrieve only the most recent N backups. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellInfo.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellInfo.md new file mode 100644 index 000000000..a11b7a356 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellInfo.md @@ -0,0 +1,29 @@ +--- +title: GetCellInfo +series: vtctldclient +--- +## vtctldclient GetCellInfo + +Gets the CellInfo object for the given cell. + +``` +vtctldclient GetCellInfo +``` + +### Options + +``` + -h, --help help for GetCellInfo +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellInfoNames.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellInfoNames.md new file mode 100644 index 000000000..e4f45cb6b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellInfoNames.md @@ -0,0 +1,29 @@ +--- +title: GetCellInfoNames +series: vtctldclient +--- +## vtctldclient GetCellInfoNames + +Lists the names of all cells in the cluster. + +``` +vtctldclient GetCellInfoNames +``` + +### Options + +``` + -h, --help help for GetCellInfoNames +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellsAliases.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellsAliases.md new file mode 100644 index 000000000..35c69556c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetCellsAliases.md @@ -0,0 +1,29 @@ +--- +title: GetCellsAliases +series: vtctldclient +--- +## vtctldclient GetCellsAliases + +Gets all CellsAlias objects in the cluster. + +``` +vtctldclient GetCellsAliases +``` + +### Options + +``` + -h, --help help for GetCellsAliases +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetFullStatus.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetFullStatus.md new file mode 100644 index 000000000..8e97efa14 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetFullStatus.md @@ -0,0 +1,29 @@ +--- +title: GetFullStatus +series: vtctldclient +--- +## vtctldclient GetFullStatus + +Outputs a JSON structure that contains full status of MySQL including the replication information, semi-sync information, GTID information among others. + +``` +vtctldclient GetFullStatus +``` + +### Options + +``` + -h, --help help for GetFullStatus +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetKeyspace.md new file mode 100644 index 000000000..d876f8e16 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetKeyspace.md @@ -0,0 +1,29 @@ +--- +title: GetKeyspace +series: vtctldclient +--- +## vtctldclient GetKeyspace + +Returns information about the given keyspace from the topology. + +``` +vtctldclient GetKeyspace +``` + +### Options + +``` + -h, --help help for GetKeyspace +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetKeyspaces.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetKeyspaces.md new file mode 100644 index 000000000..707ba89d8 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetKeyspaces.md @@ -0,0 +1,29 @@ +--- +title: GetKeyspaces +series: vtctldclient +--- +## vtctldclient GetKeyspaces + +Returns information about every keyspace in the topology. + +``` +vtctldclient GetKeyspaces +``` + +### Options + +``` + -h, --help help for GetKeyspaces +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetPermissions.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetPermissions.md new file mode 100644 index 000000000..655a94208 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetPermissions.md @@ -0,0 +1,29 @@ +--- +title: GetPermissions +series: vtctldclient +--- +## vtctldclient GetPermissions + +Displays the permissions for a tablet. + +``` +vtctldclient GetPermissions +``` + +### Options + +``` + -h, --help help for GetPermissions +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetRoutingRules.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetRoutingRules.md new file mode 100644 index 000000000..0f66e607b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetRoutingRules.md @@ -0,0 +1,29 @@ +--- +title: GetRoutingRules +series: vtctldclient +--- +## vtctldclient GetRoutingRules + +Displays the VSchema routing rules. + +``` +vtctldclient GetRoutingRules +``` + +### Options + +``` + -h, --help help for GetRoutingRules +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSchema.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSchema.md new file mode 100644 index 000000000..890ec6f96 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSchema.md @@ -0,0 +1,35 @@ +--- +title: GetSchema +series: vtctldclient +--- +## vtctldclient GetSchema + +Displays the full schema for a tablet, optionally restricted to the specified tables/views. + +``` +vtctldclient GetSchema [--tables TABLES ...] [--exclude-tables EXCLUDE_TABLES ...] [{--table-names-only | --table-sizes-only}] [--include-views] alias +``` + +### Options + +``` + --exclude-tables /regexp/ List of tables to exclude from the result. Each is either an exact match, or a regular expression of the form /regexp/. + -h, --help help for GetSchema + --include-views Includes views in the output in addition to base tables. + -n, --table-names-only Display only table names in the result. + --table-schema-only Skip introspecting columns and fields metadata. + -s, --table-sizes-only Display only size information for matching tables. Ignored if --table-names-only is set. + --tables /regexp/ List of tables to display the schema for. Each is either an exact match, or a regular expression of the form /regexp/. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetShard.md new file mode 100644 index 000000000..4908799f4 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetShard.md @@ -0,0 +1,29 @@ +--- +title: GetShard +series: vtctldclient +--- +## vtctldclient GetShard + +Returns information about a shard in the topology. + +``` +vtctldclient GetShard +``` + +### Options + +``` + -h, --help help for GetShard +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetShardRoutingRules.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetShardRoutingRules.md new file mode 100644 index 000000000..f3ea1e6ae --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetShardRoutingRules.md @@ -0,0 +1,37 @@ +--- +title: GetShardRoutingRules +series: vtctldclient +--- +## vtctldclient GetShardRoutingRules + +Displays the currently active shard routing rules as a JSON document. + +### Synopsis + +Displays the currently active shard routing rules as a JSON document. + +See the documentation on shard level migrations[1] for more information. + +[1]: https://vitess.io/docs/reference/vreplication/shardlevelmigrations/ + +``` +vtctldclient GetShardRoutingRules +``` + +### Options + +``` + -h, --help help for GetShardRoutingRules +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvKeyspaceNames.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvKeyspaceNames.md new file mode 100644 index 000000000..f97a3cd3b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvKeyspaceNames.md @@ -0,0 +1,29 @@ +--- +title: GetSrvKeyspaceNames +series: vtctldclient +--- +## vtctldclient GetSrvKeyspaceNames + +Outputs a JSON mapping of cell=>keyspace names served in that cell. Omit to query all cells. + +``` +vtctldclient GetSrvKeyspaceNames [ ...] +``` + +### Options + +``` + -h, --help help for GetSrvKeyspaceNames +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvKeyspaces.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvKeyspaces.md new file mode 100644 index 000000000..fcbe003c9 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvKeyspaces.md @@ -0,0 +1,29 @@ +--- +title: GetSrvKeyspaces +series: vtctldclient +--- +## vtctldclient GetSrvKeyspaces + +Returns the SrvKeyspaces for the given keyspace in one or more cells. + +``` +vtctldclient GetSrvKeyspaces [ ...] +``` + +### Options + +``` + -h, --help help for GetSrvKeyspaces +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvVSchema.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvVSchema.md new file mode 100644 index 000000000..1e4b0ba68 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvVSchema.md @@ -0,0 +1,29 @@ +--- +title: GetSrvVSchema +series: vtctldclient +--- +## vtctldclient GetSrvVSchema + +Returns the SrvVSchema for the given cell. + +``` +vtctldclient GetSrvVSchema cell +``` + +### Options + +``` + -h, --help help for GetSrvVSchema +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvVSchemas.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvVSchemas.md new file mode 100644 index 000000000..ab9e0c420 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetSrvVSchemas.md @@ -0,0 +1,29 @@ +--- +title: GetSrvVSchemas +series: vtctldclient +--- +## vtctldclient GetSrvVSchemas + +Returns the SrvVSchema for all cells, optionally filtered by the given cells. + +``` +vtctldclient GetSrvVSchemas [ ...] +``` + +### Options + +``` + -h, --help help for GetSrvVSchemas +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTablet.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTablet.md new file mode 100644 index 000000000..41fc9eb2f --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTablet.md @@ -0,0 +1,29 @@ +--- +title: GetTablet +series: vtctldclient +--- +## vtctldclient GetTablet + +Outputs a JSON structure that contains information about the tablet. + +``` +vtctldclient GetTablet +``` + +### Options + +``` + -h, --help help for GetTablet +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTabletVersion.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTabletVersion.md new file mode 100644 index 000000000..7cf90b2cb --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTabletVersion.md @@ -0,0 +1,29 @@ +--- +title: GetTabletVersion +series: vtctldclient +--- +## vtctldclient GetTabletVersion + +Print the version of a tablet from its debug vars. + +``` +vtctldclient GetTabletVersion +``` + +### Options + +``` + -h, --help help for GetTabletVersion +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTablets.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTablets.md new file mode 100644 index 000000000..23df6f89a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTablets.md @@ -0,0 +1,57 @@ +--- +title: GetTablets +series: vtctldclient +--- +## vtctldclient GetTablets + +Looks up tablets according to filter criteria. + +### Synopsis + +Looks up tablets according to the filter criteria. + +If --tablet-alias is passed, none of the other filters (tablet-type, keyspace, +shard, cell) may be passed, and tablets are looked up by tablet alias only. + +If --keyspace is passed, then all tablets in the keyspace are retrieved. The +--shard flag may also be passed to further narrow the set of tablets to that +. Passing --shard without also passing --keyspace will fail. + +If --tablet-type is passed, only tablets of the specified type will be +returned. Valid tablet types are: +"backup", "drained", "experimental", "primary", "rdonly", "replica", "restore", "spare". + +Passing --cell limits the set of tablets to those in the specified cells. The +--cell flag accepts a CSV argument (e.g. --cell "c1,c2") and may be repeated +(e.g. --cell "c1" --cell "c2"). + +Valid output formats are "awk" and "json". + +``` +vtctldclient GetTablets [--strict] [{--cell $c1 [--cell $c2 ...] [--tablet-type $t1] [--keyspace $ks [--shard $shard]], --tablet-alias $alias}] +``` + +### Options + +``` + -c, --cell strings List of cells to filter tablets by. + --format string Output format to use; valid choices are (json, awk). (default "awk") + -h, --help help for GetTablets + -k, --keyspace string Keyspace to filter tablets by. + -s, --shard string Shard to filter tablets by. + --strict Require all cells to return successful tablet data. Without --strict, tablet listings may be partial. + -t, --tablet-alias strings List of tablet aliases to filter by. + --tablet-type topodatapb.TabletType Tablet type to filter by (e.g. primary or replica). (default UNKNOWN) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTopologyPath.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTopologyPath.md new file mode 100644 index 000000000..0b3202600 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetTopologyPath.md @@ -0,0 +1,29 @@ +--- +title: GetTopologyPath +series: vtctldclient +--- +## vtctldclient GetTopologyPath + +Gets the value associated with the particular path (key) in the topology server. + +``` +vtctldclient GetTopologyPath +``` + +### Options + +``` + -h, --help help for GetTopologyPath +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetVSchema.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetVSchema.md new file mode 100644 index 000000000..5b1448df3 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetVSchema.md @@ -0,0 +1,29 @@ +--- +title: GetVSchema +series: vtctldclient +--- +## vtctldclient GetVSchema + +Prints a JSON representation of a keyspace's topo record. + +``` +vtctldclient GetVSchema +``` + +### Options + +``` + -h, --help help for GetVSchema +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetWorkflows.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetWorkflows.md new file mode 100644 index 000000000..056b259b7 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_GetWorkflows.md @@ -0,0 +1,30 @@ +--- +title: GetWorkflows +series: vtctldclient +--- +## vtctldclient GetWorkflows + +Gets all vreplication workflows (Reshard, MoveTables, etc) in the given keyspace. + +``` +vtctldclient GetWorkflows +``` + +### Options + +``` + -h, --help help for GetWorkflows + -a, --show-all Show all workflows instead of just active workflows. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_InitShardPrimary.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_InitShardPrimary.md new file mode 100644 index 000000000..3f2701e36 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_InitShardPrimary.md @@ -0,0 +1,41 @@ +--- +title: InitShardPrimary +series: vtctldclient +--- +## vtctldclient InitShardPrimary + +Sets the initial primary for the shard. + +### Synopsis + +This command has been deprecated. Please use PlannedReparentShard instead. + +Sets the initial primary for the shard. + +This will make all other tablets in the shard become replicas of the promoted tablet. +WARNING: this can cause data loss on an already-replicating shard. + + +``` +vtctldclient InitShardPrimary +``` + +### Options + +``` + --force Force the reparent even if the provided tablet is not writable or the shard primary. + -h, --help help for InitShardPrimary + --wait-replicas-timeout duration Time to wait for replicas to catch up in reparenting. (default 30s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_LegacyVtctlCommand.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_LegacyVtctlCommand.md new file mode 100644 index 000000000..03784d6d4 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_LegacyVtctlCommand.md @@ -0,0 +1,62 @@ +--- +title: LegacyVtctlCommand +series: vtctldclient +--- +## vtctldclient LegacyVtctlCommand + +Invoke a legacy vtctlclient command. Flag parsing is best effort. + +### Synopsis + +LegacyVtctlCommand uses the legacy vtctl grpc client to make an ExecuteVtctlCommand +rpc to a vtctld. + +This command exists to support a smooth transition of any scripts that relied on +vtctlclient during the migration to the new vtctldclient, and will be removed, +following the Vitess project's standard deprecation cycle, once all commands +have been migrated to the new VtctldServer api. + +To see the list of available legacy commands, run "LegacyVtctlCommand -- help". +Note that, as with the old client, this requires a running server, as the flag +parsing and help/usage text generation, is done server-side. + +Also note that, in order to defer that flag parsing to the server side, you must +use the double-dash ("--") after the LegacyVtctlCommand subcommand string, or +the client-side flag parsing library we are using will attempt to parse those +flags (and fail). + +``` +vtctldclient LegacyVtctlCommand -- [flags ...] [args ...] +``` + +### Examples + +``` +LegacyVtctlCommand help # displays this help message +LegacyVtctlCommand -- help # displays help for supported legacy vtctl commands + +# When using legacy command that take arguments, a double dash must be used +# before the first flag argument, like in the first example. The double dash may +# be used, however, at any point after the "LegacyVtctlCommand" string, as in +# the second example. +LegacyVtctlCommand AddCellInfo -- --server_address "localhost:1234" --root "/vitess/cell1" +LegacyVtctlCommand -- AddCellInfo --server_address "localhost:5678" --root "/vitess/cell1" +``` + +### Options + +``` + -h, --help help for LegacyVtctlCommand +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md new file mode 100644 index 000000000..1cedd9d89 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/_index.md @@ -0,0 +1,43 @@ +--- +title: MoveTables +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables + +Perform commands related to moving tables from a source keyspace to a target keyspace. + +### Synopsis + +MoveTables commands: Create, Show, Status, SwitchTraffic, ReverseTraffic, Stop, Start, Cancel, and Delete. +See the --help output for each command for more details. + +### Options + +``` + --format string The format of the output; supported formats are: text,json. (default "text") + -h, --help help for MoveTables + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. +* [vtctldclient MoveTables cancel](./vtctldclient_movetables_cancel/) - Cancel a MoveTables VReplication workflow. +* [vtctldclient MoveTables complete](./vtctldclient_movetables_complete/) - Complete a MoveTables VReplication workflow. +* [vtctldclient MoveTables create](./vtctldclient_movetables_create/) - Create and optionally run a MoveTables VReplication workflow. +* [vtctldclient MoveTables reversetraffic](./vtctldclient_movetables_reversetraffic/) - Reverse traffic for a MoveTables VReplication workflow. +* [vtctldclient MoveTables show](./vtctldclient_movetables_show/) - Show the details for a MoveTables VReplication workflow. +* [vtctldclient MoveTables start](./vtctldclient_movetables_start/) - Start a MoveTables workflow. +* [vtctldclient MoveTables status](./vtctldclient_movetables_status/) - Show the current status for a MoveTables VReplication workflow. +* [vtctldclient MoveTables stop](./vtctldclient_movetables_stop/) - Stop a MoveTables workflow. +* [vtctldclient MoveTables switchtraffic](./vtctldclient_movetables_switchtraffic/) - Switch traffic for a MoveTables VReplication workflow. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_cancel.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_cancel.md new file mode 100644 index 000000000..bdaaa4fda --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_cancel.md @@ -0,0 +1,39 @@ +--- +title: MoveTables cancel +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables cancel + +Cancel a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables cancel +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer cancel +``` + +### Options + +``` + -h, --help help for cancel +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_complete.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_complete.md new file mode 100644 index 000000000..2fa6e1884 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_complete.md @@ -0,0 +1,39 @@ +--- +title: MoveTables complete +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables complete + +Complete a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables complete +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer complete +``` + +### Options + +``` + -h, --help help for complete +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md new file mode 100644 index 000000000..1a9143cc2 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md @@ -0,0 +1,54 @@ +--- +title: MoveTables create +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables create + +Create and optionally run a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables create +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer create --source-keyspace commerce --cells zone1 --cells zone2 --tablet-types replica +``` + +### Options + +``` + --all-tables Copy all tables from the source. + --atomic-copy (EXPERIMENTAL) A single copy phase is run for all tables from the source. Use this, for example, if your source keyspace has tables which use foreign key constraints. + --auto-start Start the MoveTables workflow after creating it. (default true) + -c, --cells strings Cells and/or CellAliases to copy table data from. + --defer-secondary-keys Defer secondary index creation for a table until after it has been copied. + --exclude-tables strings Source tables to exclude from copying. + -h, --help help for create + --no-routing-rules (Advanced) Do not create routing rules while creating the workflow. See the reference documentation for limitations if you use this flag. + --on-ddl string What to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. (default "IGNORE") + --source-keyspace string Keyspace where the tables are being moved from. + --source-shards strings Source shards to copy data from when performing a partial moveTables (experimental). + --source-time-zone string Specifying this causes any DATETIME fields to be converted from the given time zone into UTC. + --stop-after-copy Stop the MoveTables workflow after it's finished copying the existing rows and before it starts replicating changes. + --tables strings Source tables to copy. + --tablet-types strings Source tablet types to replicate table data from (e.g. PRIMARY,REPLICA,RDONLY). + --tablet-types-in-preference-order When performing source tablet selection, look for candidates in the type order as they are listed in the tablet-types flag. (default true) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md new file mode 100644 index 000000000..e6834a3ba --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md @@ -0,0 +1,45 @@ +--- +title: MoveTables reversetraffic +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables reversetraffic + +Reverse traffic for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables reversetraffic +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer reversetraffic +``` + +### Options + +``` + -c, --cells strings Cells and/or CellAliases to switch traffic in. + --dry-run Print the actions that would be taken and report any known errors that would have occurred. + --enable-reverse-replication Setup replication going back to the original source keyspace to support rolling back the traffic cutover. (default true) + -h, --help help for reversetraffic + --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this. (default 30s) + --tablet-types strings Tablet types to switch traffic for. + --timeout duration Specifies the maximum time to wait, in seconds, for VReplication to catch up on primary tablets. The traffic switch will be cancelled on timeout. (default 30s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_show.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_show.md new file mode 100644 index 000000000..edca1affb --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_show.md @@ -0,0 +1,39 @@ +--- +title: MoveTables show +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables show + +Show the details for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables show +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer show +``` + +### Options + +``` + -h, --help help for show +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_start.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_start.md new file mode 100644 index 000000000..2d7507236 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_start.md @@ -0,0 +1,39 @@ +--- +title: MoveTables start +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables start + +Start a MoveTables workflow. + +``` +vtctldclient MoveTables start +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer start +``` + +### Options + +``` + -h, --help help for start +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_status.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_status.md new file mode 100644 index 000000000..e24c30891 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_status.md @@ -0,0 +1,39 @@ +--- +title: MoveTables status +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables status + +Show the current status for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables status +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer status +``` + +### Options + +``` + -h, --help help for status +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_stop.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_stop.md new file mode 100644 index 000000000..316e93985 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_stop.md @@ -0,0 +1,39 @@ +--- +title: MoveTables stop +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables stop + +Stop a MoveTables workflow. + +``` +vtctldclient MoveTables stop +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer stop +``` + +### Options + +``` + -h, --help help for stop +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md new file mode 100644 index 000000000..9267aa907 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md @@ -0,0 +1,46 @@ +--- +title: MoveTables switchtraffic +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient MoveTables switchtraffic + +Switch traffic for a MoveTables VReplication workflow. + +``` +vtctldclient MoveTables switchtraffic +``` + +### Examples + +``` +vtctldclient --server localhost:15999 MoveTables --workflow commerce2customer --target-keyspace customer switchtraffic --tablet-types "replica,rdonly" +``` + +### Options + +``` + -c, --cells strings Cells and/or CellAliases to switch traffic in. + --dry-run Print the actions that would be taken and report any known errors that would have occurred. + --enable-reverse-replication Setup replication going back to the original source keyspace to support rolling back the traffic cutover. (default true) + -h, --help help for switchtraffic + --initialize-target-sequences When moving tables from an unsharded keyspace to a sharded keyspace, initialize any sequences that are being used on the target when switching writes. + --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this. (default 30s) + --tablet-types strings Tablet types to switch traffic for. + --timeout duration Specifies the maximum time to wait, in seconds, for VReplication to catch up on primary tablets. The traffic switch will be cancelled on timeout. (default 30s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient MoveTables](../) - Perform commands related to moving tables from a source keyspace to a target keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/_index.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/_index.md new file mode 100644 index 000000000..417e1dbcd --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/_index.md @@ -0,0 +1,34 @@ +--- +title: OnlineDDL +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL + +Operates on online DDL (schema migrations). + +### Options + +``` + -h, --help help for OnlineDDL +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. +* [vtctldclient OnlineDDL cancel](./vtctldclient_onlineddl_cancel/) - Cancel one or all migrations, terminating any running ones as needed. +* [vtctldclient OnlineDDL cleanup](./vtctldclient_onlineddl_cleanup/) - Mark a given schema migration ready for artifact cleanup. +* [vtctldclient OnlineDDL complete](./vtctldclient_onlineddl_complete/) - Complete one or all migrations executed with --postpone-completion +* [vtctldclient OnlineDDL launch](./vtctldclient_onlineddl_launch/) - Launch one or all migrations executed with --postpone-launch +* [vtctldclient OnlineDDL retry](./vtctldclient_onlineddl_retry/) - Mark a given schema migration for retry. +* [vtctldclient OnlineDDL show](./vtctldclient_onlineddl_show/) - Display information about online DDL operations. +* [vtctldclient OnlineDDL throttle](./vtctldclient_onlineddl_throttle/) - Throttles one or all migrations +* [vtctldclient OnlineDDL unthrottle](./vtctldclient_onlineddl_unthrottle/) - Unthrottles one or all migrations + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_cancel.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_cancel.md new file mode 100644 index 000000000..dad214cc8 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_cancel.md @@ -0,0 +1,36 @@ +--- +title: OnlineDDL cancel +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL cancel + +Cancel one or all migrations, terminating any running ones as needed. + +``` +vtctldclient OnlineDDL cancel +``` + +### Examples + +``` +OnlineDDL cancel test_keyspace 82fa54ac_e83e_11ea_96b7_f875a4d24e90 +``` + +### Options + +``` + -h, --help help for cancel +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_cleanup.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_cleanup.md new file mode 100644 index 000000000..028527e96 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_cleanup.md @@ -0,0 +1,36 @@ +--- +title: OnlineDDL cleanup +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL cleanup + +Mark a given schema migration ready for artifact cleanup. + +``` +vtctldclient OnlineDDL cleanup +``` + +### Examples + +``` +OnlineDDL cleanup test_keyspace 82fa54ac_e83e_11ea_96b7_f875a4d24e90 +``` + +### Options + +``` + -h, --help help for cleanup +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_complete.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_complete.md new file mode 100644 index 000000000..619b12a0c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_complete.md @@ -0,0 +1,36 @@ +--- +title: OnlineDDL complete +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL complete + +Complete one or all migrations executed with --postpone-completion + +``` +vtctldclient OnlineDDL complete +``` + +### Examples + +``` +OnlineDDL complete test_keyspace 82fa54ac_e83e_11ea_96b7_f875a4d24e90 +``` + +### Options + +``` + -h, --help help for complete +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_launch.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_launch.md new file mode 100644 index 000000000..91f77ce8e --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_launch.md @@ -0,0 +1,36 @@ +--- +title: OnlineDDL launch +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL launch + +Launch one or all migrations executed with --postpone-launch + +``` +vtctldclient OnlineDDL launch +``` + +### Examples + +``` +OnlineDDL launch test_keyspace 82fa54ac_e83e_11ea_96b7_f875a4d24e90 +``` + +### Options + +``` + -h, --help help for launch +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_retry.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_retry.md new file mode 100644 index 000000000..65bff1be5 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_retry.md @@ -0,0 +1,36 @@ +--- +title: OnlineDDL retry +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL retry + +Mark a given schema migration for retry. + +``` +vtctldclient OnlineDDL retry +``` + +### Examples + +``` +vtctl OnlineDDL retry test_keyspace 82fa54ac_e83e_11ea_96b7_f875a4d24e90 +``` + +### Options + +``` + -h, --help help for retry +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_show.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_show.md new file mode 100644 index 000000000..991ed3911 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_show.md @@ -0,0 +1,47 @@ +--- +title: OnlineDDL show +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL show + +Display information about online DDL operations. + +``` +vtctldclient OnlineDDL show +``` + +### Examples + +``` +OnlineDDL show test_keyspace 82fa54ac_e83e_11ea_96b7_f875a4d24e90 +OnlineDDL show test_keyspace all +OnlineDDL show --order descending test_keyspace all +OnlineDDL show --limit 10 test_keyspace all +OnlineDDL show --skip 5 --limit 10 test_keyspace all +OnlineDDL show test_keyspace running +OnlineDDL show test_keyspace complete +OnlineDDL show test_keyspace failed +``` + +### Options + +``` + -h, --help help for show + --json Output JSON instead of human-readable table. + --limit uint Limit number of rows returned in output. + --order id Sort the results by id property of the Schema migration. (default "asc") + --skip uint Skip specified number of rows returned in output. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_throttle.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_throttle.md new file mode 100644 index 000000000..6c0dfc637 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_throttle.md @@ -0,0 +1,36 @@ +--- +title: OnlineDDL throttle +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL throttle + +Throttles one or all migrations + +``` +vtctldclient OnlineDDL throttle +``` + +### Examples + +``` +OnlineDDL throttle all +``` + +### Options + +``` + -h, --help help for throttle +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_unthrottle.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_unthrottle.md new file mode 100644 index 000000000..874d62616 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_OnlineDDL/vtctldclient_OnlineDDL_unthrottle.md @@ -0,0 +1,36 @@ +--- +title: OnlineDDL unthrottle +series: vtctldclient +commit: 476ca265d0583549c05a3ab88f76bc8d24174364 +--- +## vtctldclient OnlineDDL unthrottle + +Unthrottles one or all migrations + +``` +vtctldclient OnlineDDL unthrottle +``` + +### Examples + +``` +OnlineDDL unthrottle all +``` + +### Options + +``` + -h, --help help for unthrottle +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient OnlineDDL](../) - Operates on online DDL (schema migrations). + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_PingTablet.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_PingTablet.md new file mode 100644 index 000000000..0723fdcd1 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_PingTablet.md @@ -0,0 +1,29 @@ +--- +title: PingTablet +series: vtctldclient +--- +## vtctldclient PingTablet + +Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations. + +``` +vtctldclient PingTablet +``` + +### Options + +``` + -h, --help help for PingTablet +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_PlannedReparentShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_PlannedReparentShard.md new file mode 100644 index 000000000..7050c5196 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_PlannedReparentShard.md @@ -0,0 +1,32 @@ +--- +title: PlannedReparentShard +series: vtctldclient +--- +## vtctldclient PlannedReparentShard + +Reparents the shard to a new primary, or away from an old primary. Both the old and new primaries must be up and running. + +``` +vtctldclient PlannedReparentShard +``` + +### Options + +``` + --avoid-primary string Alias of a tablet that should not be the primary; i.e. "reparent to any other tablet if this one is the primary". + -h, --help help for PlannedReparentShard + --new-primary string Alias of a tablet that should be the new primary. + --wait-replicas-timeout duration Time to wait for replicas to catch up on replication both before and after reparenting. (default 15s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RebuildKeyspaceGraph.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RebuildKeyspaceGraph.md new file mode 100644 index 000000000..145c9d924 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RebuildKeyspaceGraph.md @@ -0,0 +1,31 @@ +--- +title: RebuildKeyspaceGraph +series: vtctldclient +--- +## vtctldclient RebuildKeyspaceGraph + +Rebuilds the serving data for the keyspace(s). This command may trigger an update to all connected clients. + +``` +vtctldclient RebuildKeyspaceGraph [--cells=c1,c2,...] [--allow-partial] ks1 [ks2 ...] +``` + +### Options + +``` + --allow-partial Specifies whether a SNAPSHOT keyspace is allowed to serve with an incomplete set of shards. Ignored for all other types of keyspaces. + -c, --cells strings Specifies a comma-separated list of cells to update. + -h, --help help for RebuildKeyspaceGraph +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RebuildVSchemaGraph.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RebuildVSchemaGraph.md new file mode 100644 index 000000000..d08781256 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RebuildVSchemaGraph.md @@ -0,0 +1,30 @@ +--- +title: RebuildVSchemaGraph +series: vtctldclient +--- +## vtctldclient RebuildVSchemaGraph + +Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided). + +``` +vtctldclient RebuildVSchemaGraph [--cells=c1,c2,...] +``` + +### Options + +``` + -c, --cells strings Specifies a comma-separated list of cells to look for tablets. + -h, --help help for RebuildVSchemaGraph +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RefreshState.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RefreshState.md new file mode 100644 index 000000000..e19222dd5 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RefreshState.md @@ -0,0 +1,29 @@ +--- +title: RefreshState +series: vtctldclient +--- +## vtctldclient RefreshState + +Reloads the tablet record on the specified tablet. + +``` +vtctldclient RefreshState +``` + +### Options + +``` + -h, --help help for RefreshState +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RefreshStateByShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RefreshStateByShard.md new file mode 100644 index 000000000..c52fe6233 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RefreshStateByShard.md @@ -0,0 +1,30 @@ +--- +title: RefreshStateByShard +series: vtctldclient +--- +## vtctldclient RefreshStateByShard + +Reloads the tablet record all tablets in the shard, optionally limited to the specified cells. + +``` +vtctldclient RefreshStateByShard [--cell ...] +``` + +### Options + +``` + -c, --cells strings If specified, only call RefreshState on tablets in the specified cells. If empty, all cells are considered. + -h, --help help for RefreshStateByShard +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchema.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchema.md new file mode 100644 index 000000000..849e1b900 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchema.md @@ -0,0 +1,29 @@ +--- +title: ReloadSchema +series: vtctldclient +--- +## vtctldclient ReloadSchema + +Reloads the schema on a remote tablet. + +``` +vtctldclient ReloadSchema +``` + +### Options + +``` + -h, --help help for ReloadSchema +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchemaKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchemaKeyspace.md new file mode 100644 index 000000000..a5c47ce9b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchemaKeyspace.md @@ -0,0 +1,31 @@ +--- +title: ReloadSchemaKeyspace +series: vtctldclient +--- +## vtctldclient ReloadSchemaKeyspace + +Reloads the schema on all tablets in a keyspace. This is done on a best-effort basis. + +``` +vtctldclient ReloadSchemaKeyspace [--concurrency=] [--include-primary] +``` + +### Options + +``` + --concurrency uint32 Number of tablets to reload in parallel. Set to zero for unbounded concurrency. (default 10) + -h, --help help for ReloadSchemaKeyspace + --include-primary Also reload the primary tablets. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchemaShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchemaShard.md new file mode 100644 index 000000000..37ba5818e --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReloadSchemaShard.md @@ -0,0 +1,31 @@ +--- +title: ReloadSchemaShard +series: vtctldclient +--- +## vtctldclient ReloadSchemaShard + +Reloads the schema on all tablets in a shard. This is done on a best-effort basis. + +``` +vtctldclient ReloadSchemaShard [--concurrency=10] [--include-primary] +``` + +### Options + +``` + --concurrency uint32 Number of tablets to reload in parallel. Set to zero for unbounded concurrency. (default 10) + -h, --help help for ReloadSchemaShard + --include-primary Also reload the primary tablet. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveBackup.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveBackup.md new file mode 100644 index 000000000..0b89878e1 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveBackup.md @@ -0,0 +1,29 @@ +--- +title: RemoveBackup +series: vtctldclient +--- +## vtctldclient RemoveBackup + +Removes the given backup from the BackupStorage used by vtctld. + +``` +vtctldclient RemoveBackup +``` + +### Options + +``` + -h, --help help for RemoveBackup +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveKeyspaceCell.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveKeyspaceCell.md new file mode 100644 index 000000000..1e5cd42bc --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveKeyspaceCell.md @@ -0,0 +1,31 @@ +--- +title: RemoveKeyspaceCell +series: vtctldclient +--- +## vtctldclient RemoveKeyspaceCell + +Removes the specified cell from the Cells list for all shards in the specified keyspace (by calling RemoveShardCell on every shard). It also removes the SrvKeyspace for that keyspace in that cell. + +``` +vtctldclient RemoveKeyspaceCell [--force|-f] [--recursive|-r] +``` + +### Options + +``` + -f, --force Proceed even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. + -h, --help help for RemoveKeyspaceCell + -r, --recursive Also delete all tablets in that cell beloning to the specified keyspace. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveShardCell.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveShardCell.md new file mode 100644 index 000000000..7eba51518 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RemoveShardCell.md @@ -0,0 +1,31 @@ +--- +title: RemoveShardCell +series: vtctldclient +--- +## vtctldclient RemoveShardCell + +Remove the specified cell from the specified shard's Cells list. + +``` +vtctldclient RemoveShardCell [--force|-f] [--recursive|-r] +``` + +### Options + +``` + -f, --force Proceed even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. + -h, --help help for RemoveShardCell + -r, --recursive Also delete all tablets in that cell beloning to the specified shard. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReparentTablet.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReparentTablet.md new file mode 100644 index 000000000..83c2d7014 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ReparentTablet.md @@ -0,0 +1,29 @@ +--- +title: ReparentTablet +series: vtctldclient +--- +## vtctldclient ReparentTablet + +Reparent a tablet to the current primary in the shard. + +``` +vtctldclient ReparentTablet +``` + +### Options + +``` + -h, --help help for ReparentTablet +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/_index.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/_index.md new file mode 100644 index 000000000..b8f50ac1c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/_index.md @@ -0,0 +1,43 @@ +--- +title: Reshard +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard + +Perform commands related to resharding a keyspace. + +### Synopsis + +Reshard commands: Create, Show, Status, SwitchTraffic, ReverseTraffic, Stop, Start, Cancel, and Delete. +See the --help output for each command for more details. + +### Options + +``` + --format string The format of the output; supported formats are: text,json. (default "text") + -h, --help help for Reshard + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. +* [vtctldclient Reshard cancel](./vtctldclient_reshard_cancel/) - Cancel a Reshard VReplication workflow. +* [vtctldclient Reshard complete](./vtctldclient_reshard_complete/) - Complete a MoveTables VReplication workflow. +* [vtctldclient Reshard create](./vtctldclient_reshard_create/) - Create and optionally run a reshard VReplication workflow. +* [vtctldclient Reshard reversetraffic](./vtctldclient_reshard_reversetraffic/) - Reverse traffic for a Reshard VReplication workflow. +* [vtctldclient Reshard show](./vtctldclient_reshard_show/) - Show the details for a Reshard VReplication workflow. +* [vtctldclient Reshard start](./vtctldclient_reshard_start/) - Start a Reshard workflow. +* [vtctldclient Reshard status](./vtctldclient_reshard_status/) - Show the current status for a Reshard VReplication workflow. +* [vtctldclient Reshard stop](./vtctldclient_reshard_stop/) - Stop a Reshard workflow. +* [vtctldclient Reshard switchtraffic](./vtctldclient_reshard_switchtraffic/) - Switch traffic for a Reshard VReplication workflow. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_cancel.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_cancel.md new file mode 100644 index 000000000..0dffedff5 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_cancel.md @@ -0,0 +1,39 @@ +--- +title: Reshard cancel +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard cancel + +Cancel a Reshard VReplication workflow. + +``` +vtctldclient Reshard cancel +``` + +### Examples + +``` +vtctldclient --server localhost:15999 Reshard --workflow cust2cust --target-keyspace customer cancel +``` + +### Options + +``` + -h, --help help for cancel +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_complete.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_complete.md new file mode 100644 index 000000000..866a7d8d6 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_complete.md @@ -0,0 +1,39 @@ +--- +title: Reshard complete +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard complete + +Complete a MoveTables VReplication workflow. + +``` +vtctldclient Reshard complete +``` + +### Examples + +``` +vtctldclient --server localhost:15999 movetables --workflow commerce2customer --target-keyspace customer complete +``` + +### Options + +``` + -h, --help help for complete +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_create.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_create.md new file mode 100644 index 000000000..fd5c3159c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_create.md @@ -0,0 +1,49 @@ +--- +title: Reshard create +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard create + +Create and optionally run a reshard VReplication workflow. + +``` +vtctldclient Reshard create +``` + +### Examples + +``` +vtctldclient --server localhost:15999 reshard --workflow customer2customer --target-keyspace customer create --source_shards="0" --target_shards="-80,80-" --cells zone1 --cells zone2 --tablet-types replica +``` + +### Options + +``` + --auto-start Start the MoveTables workflow after creating it. (default true) + -c, --cells strings Cells and/or CellAliases to copy table data from. + --defer-secondary-keys Defer secondary index creation for a table until after it has been copied. + -h, --help help for create + --on-ddl string What to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. (default "IGNORE") + --skip-schema-copy Skip copying the schema from the source shards to the target shards. + --source-shards strings Source shards. + --stop-after-copy Stop the MoveTables workflow after it's finished copying the existing rows and before it starts replicating changes. + --tablet-types strings Source tablet types to replicate table data from (e.g. PRIMARY,REPLICA,RDONLY). + --tablet-types-in-preference-order When performing source tablet selection, look for candidates in the type order as they are listed in the tablet-types flag. (default true) + --target-shards strings Target shards. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_reversetraffic.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_reversetraffic.md new file mode 100644 index 000000000..756e25356 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_reversetraffic.md @@ -0,0 +1,45 @@ +--- +title: Reshard reversetraffic +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard reversetraffic + +Reverse traffic for a Reshard VReplication workflow. + +``` +vtctldclient Reshard reversetraffic +``` + +### Examples + +``` +vtctldclient --server localhost:15999 Reshard --workflow cust2cust --target-keyspace customer reversetraffic +``` + +### Options + +``` + -c, --cells strings Cells and/or CellAliases to switch traffic in. + --dry-run Print the actions that would be taken and report any known errors that would have occurred. + --enable-reverse-replication Setup replication going back to the original source keyspace to support rolling back the traffic cutover. (default true) + -h, --help help for reversetraffic + --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this. (default 30s) + --tablet-types strings Tablet types to switch traffic for. + --timeout duration Specifies the maximum time to wait, in seconds, for VReplication to catch up on primary tablets. The traffic switch will be cancelled on timeout. (default 30s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_show.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_show.md new file mode 100644 index 000000000..5f370d2ac --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_show.md @@ -0,0 +1,39 @@ +--- +title: Reshard show +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard show + +Show the details for a Reshard VReplication workflow. + +``` +vtctldclient Reshard show +``` + +### Examples + +``` +vtctldclient --server localhost:15999 Reshard --workflow cust2cust --target-keyspace customer show +``` + +### Options + +``` + -h, --help help for show +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_start.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_start.md new file mode 100644 index 000000000..6246d5540 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_start.md @@ -0,0 +1,39 @@ +--- +title: Reshard start +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard start + +Start a Reshard workflow. + +``` +vtctldclient Reshard start +``` + +### Examples + +``` +vtctldclient --server localhost:15999 Reshard --workflow cust2cust --target-keyspace customer start +``` + +### Options + +``` + -h, --help help for start +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_status.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_status.md new file mode 100644 index 000000000..5bba74f0b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_status.md @@ -0,0 +1,39 @@ +--- +title: Reshard status +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard status + +Show the current status for a Reshard VReplication workflow. + +``` +vtctldclient Reshard status +``` + +### Examples + +``` +vtctldclient --server localhost:15999 Reshard --workflow cust2cust --target-keyspace customer status +``` + +### Options + +``` + -h, --help help for status +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_stop.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_stop.md new file mode 100644 index 000000000..a002656f7 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_stop.md @@ -0,0 +1,39 @@ +--- +title: Reshard stop +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard stop + +Stop a Reshard workflow. + +``` +vtctldclient Reshard stop +``` + +### Examples + +``` +vtctldclient --server localhost:15999 Reshard --workflow cust2cust --target-keyspace customer stop +``` + +### Options + +``` + -h, --help help for stop +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_switchtraffic.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_switchtraffic.md new file mode 100644 index 000000000..795d56ffc --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Reshard/vtctldclient_Reshard_switchtraffic.md @@ -0,0 +1,45 @@ +--- +title: Reshard switchtraffic +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient Reshard switchtraffic + +Switch traffic for a Reshard VReplication workflow. + +``` +vtctldclient Reshard switchtraffic +``` + +### Examples + +``` +vtctldclient --server localhost:15999 Reshard --workflow cust2cust --target-keyspace customer switchtraffic --tablet-types "replica,rdonly" +``` + +### Options + +``` + -c, --cells strings Cells and/or CellAliases to switch traffic in. + --dry-run Print the actions that would be taken and report any known errors that would have occurred. + --enable-reverse-replication Setup replication going back to the original source keyspace to support rolling back the traffic cutover. (default true) + -h, --help help for switchtraffic + --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this. (default 30s) + --tablet-types strings Tablet types to switch traffic for. + --timeout duration Specifies the maximum time to wait, in seconds, for VReplication to catch up on primary tablets. The traffic switch will be cancelled on timeout. (default 30s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient Reshard](../) - Perform commands related to resharding a keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RestoreFromBackup.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RestoreFromBackup.md new file mode 100644 index 000000000..842bc2879 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RestoreFromBackup.md @@ -0,0 +1,33 @@ +--- +title: RestoreFromBackup +series: vtctldclient +--- +## vtctldclient RestoreFromBackup + +Stops mysqld on the specified tablet and restores the data from either the latest backup or closest before `backup-timestamp`. + +``` +vtctldclient RestoreFromBackup [--backup-timestamp|-t ] [--restore-to-pos ] [--dry-run] +``` + +### Options + +``` + -t, --backup-timestamp string Use the backup taken at, or closest before, this timestamp. Omit to use the latest backup. Timestamp format is "YYYY-mm-DD.HHMMSS". + --dry-run Only validate restore steps, do not actually restore data + -h, --help help for RestoreFromBackup + --restore-to-pos string Run a point in time recovery that ends with the given position. This will attempt to use one full backup followed by zero or more incremental backups + --restore-to-timestamp 2006-01-02T15:04:05Z07:00 Run a point in time recovery that restores up to, and excluding, given timestamp in RFC3339 format (2006-01-02T15:04:05Z07:00). This will attempt to use one full backup followed by zero or more incremental backups +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RunHealthCheck.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RunHealthCheck.md new file mode 100644 index 000000000..a67b4ec69 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_RunHealthCheck.md @@ -0,0 +1,29 @@ +--- +title: RunHealthCheck +series: vtctldclient +--- +## vtctldclient RunHealthCheck + +Runs a healthcheck on the remote tablet. + +``` +vtctldclient RunHealthCheck +``` + +### Options + +``` + -h, --help help for RunHealthCheck +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetKeyspaceDurabilityPolicy.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetKeyspaceDurabilityPolicy.md new file mode 100644 index 000000000..42ae74ae1 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetKeyspaceDurabilityPolicy.md @@ -0,0 +1,39 @@ +--- +title: SetKeyspaceDurabilityPolicy +series: vtctldclient +--- +## vtctldclient SetKeyspaceDurabilityPolicy + +Sets the durability-policy used by the specified keyspace. + +### Synopsis + +Sets the durability-policy used by the specified keyspace. +Durability policy governs the durability of the keyspace by describing which tablets should be sending semi-sync acknowledgements to the primary. +Possible values include 'semi_sync', 'none' and others as dictated by registered plugins. + +To set the durability policy of customer keyspace to semi_sync, you would use the following command: +SetKeyspaceDurabilityPolicy --durability-policy='semi_sync' customer + +``` +vtctldclient SetKeyspaceDurabilityPolicy [--durability-policy=policy_name] +``` + +### Options + +``` + --durability-policy string Type of durability to enforce for this keyspace. Default is none. Other values include 'semi_sync' and others as dictated by registered plugins. (default "none") + -h, --help help for SetKeyspaceDurabilityPolicy +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetShardIsPrimaryServing.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetShardIsPrimaryServing.md new file mode 100644 index 000000000..55589ae4f --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetShardIsPrimaryServing.md @@ -0,0 +1,29 @@ +--- +title: SetShardIsPrimaryServing +series: vtctldclient +--- +## vtctldclient SetShardIsPrimaryServing + +Add or remove a shard from serving. This is meant as an emergency function. It does not rebuild any serving graphs; i.e. it does not run `RebuildKeyspaceGraph`. + +``` +vtctldclient SetShardIsPrimaryServing +``` + +### Options + +``` + -h, --help help for SetShardIsPrimaryServing +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetShardTabletControl.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetShardTabletControl.md new file mode 100644 index 000000000..c6845e71c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetShardTabletControl.md @@ -0,0 +1,51 @@ +--- +title: SetShardTabletControl +series: vtctldclient +--- +## vtctldclient SetShardTabletControl + +Sets the TabletControl record for a shard and tablet type. Only use this for an emergency fix or after a finished MoveTables. + +### Synopsis + +Sets the TabletControl record for a shard and tablet type. + +Only use this for an emergency fix or after a finished MoveTables. + +Always specify the denied-tables flag for MoveTables, but never for Reshard operations. + +To set the DisableQueryService flag, keep denied-tables empty, and set --disable-query-service +to true or false. This is useful to fix Reshard operations gone wrong. + +To change the list of denied tables, specify the --denied-tables parameter with +the new list. This is useful to fix tables that are being blocked after a +MoveTables operation. + +To remove the ShardTabletControl record entirely, use the --remove flag. This is +useful after a MoveTables has finished to remove serving restrictions. + +``` +vtctldclient SetShardTabletControl [--cells=c1,c2...] [--denied-tables=t1,t2,...] [--remove] [--disable-query-service[=0|false]] +``` + +### Options + +``` + -c, --cells strings Specifies a comma-separated list of cells to update. + --denied-tables strings Specifies a comma-separated list of tables to add to the denylist (for MoveTables). Each table name is either an exact match, or a regular expression of the form '/regexp/'. + --disable-query-service Sets the DisableQueryService flag in the specified cells. This flag requires --denied-tables and --remove to be unset; if either is set, this flag is ignored. + -h, --help help for SetShardTabletControl + -r, --remove Removes the specified cells for MoveTables operations. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetWritable.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetWritable.md new file mode 100644 index 000000000..23221ddc7 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SetWritable.md @@ -0,0 +1,29 @@ +--- +title: SetWritable +series: vtctldclient +--- +## vtctldclient SetWritable + +Sets the specified tablet as writable or read-only. + +``` +vtctldclient SetWritable +``` + +### Options + +``` + -h, --help help for SetWritable +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ShardReplicationFix.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ShardReplicationFix.md new file mode 100644 index 000000000..804546f31 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ShardReplicationFix.md @@ -0,0 +1,29 @@ +--- +title: ShardReplicationFix +series: vtctldclient +--- +## vtctldclient ShardReplicationFix + +Walks through a ShardReplication object and fixes the first error encountered. + +``` +vtctldclient ShardReplicationFix +``` + +### Options + +``` + -h, --help help for ShardReplicationFix +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ShardReplicationPositions.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ShardReplicationPositions.md new file mode 100644 index 000000000..f3d91aa9e --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ShardReplicationPositions.md @@ -0,0 +1,35 @@ +--- +title: ShardReplicationPositions +series: vtctldclient +--- +## vtctldclient ShardReplicationPositions + + + +### Synopsis + +Shows the replication status of each tablet in the shard graph. +Output is sorted by tablet type, then replication position. +Use ctrl-C to interrupt the command and see partial results if needed. + +``` +vtctldclient ShardReplicationPositions +``` + +### Options + +``` + -h, --help help for ShardReplicationPositions +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SleepTablet.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SleepTablet.md new file mode 100644 index 000000000..89962584c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SleepTablet.md @@ -0,0 +1,45 @@ +--- +title: SleepTablet +series: vtctldclient +--- +## vtctldclient SleepTablet + +Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing. + +### Synopsis + +SleepTablet + +Blocks the action queue on the specified tablet for the specified duration. +This command is typically only used for testing. + +The duration is the amount of time that the action queue should be blocked. +The value is a string that contains a possibly signed sequence of decimal numbers, +each with optional fraction and a unit suffix, such as “300ms” or “1h45m”. +See the definition of the Go language’s ParseDuration[1] function for more details. +Note that, in the SleepTablet implementation, the value should be positively-signed. + +[1]: https://pkg.go.dev/time#ParseDuration + + +``` +vtctldclient SleepTablet +``` + +### Options + +``` + -h, --help help for SleepTablet +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SourceShardAdd.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SourceShardAdd.md new file mode 100644 index 000000000..2d59a588c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SourceShardAdd.md @@ -0,0 +1,31 @@ +--- +title: SourceShardAdd +series: vtctldclient +--- +## vtctldclient SourceShardAdd + +Adds the SourceShard record with the provided index for emergencies only. It does not call RefreshState for the shard primary. + +``` +vtctldclient SourceShardAdd [--key-range ] [--tables [--tables ]...] +``` + +### Options + +``` + -h, --help help for SourceShardAdd + --key-range string Key range to use for the SourceShard. + --tables strings Comma-separated lists of tables to replicate (for MoveTables). Each table name is either an exact match, or a regular expression of the form "/regexp/". +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SourceShardDelete.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SourceShardDelete.md new file mode 100644 index 000000000..c0db5914c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_SourceShardDelete.md @@ -0,0 +1,29 @@ +--- +title: SourceShardDelete +series: vtctldclient +--- +## vtctldclient SourceShardDelete + +Deletes the SourceShard record with the provided index. This should only be used for emergency cleanup. It does not call RefreshState for the shard primary. + +``` +vtctldclient SourceShardDelete +``` + +### Options + +``` + -h, --help help for SourceShardDelete +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_StartReplication.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_StartReplication.md new file mode 100644 index 000000000..2d5ba6843 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_StartReplication.md @@ -0,0 +1,29 @@ +--- +title: StartReplication +series: vtctldclient +--- +## vtctldclient StartReplication + +Starts replication on the specified tablet. + +``` +vtctldclient StartReplication +``` + +### Options + +``` + -h, --help help for StartReplication +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_StopReplication.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_StopReplication.md new file mode 100644 index 000000000..4e369b9ae --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_StopReplication.md @@ -0,0 +1,29 @@ +--- +title: StopReplication +series: vtctldclient +--- +## vtctldclient StopReplication + +Stops replication on the specified tablet. + +``` +vtctldclient StopReplication +``` + +### Options + +``` + -h, --help help for StopReplication +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_TabletExternallyReparented.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_TabletExternallyReparented.md new file mode 100644 index 000000000..ca77c772c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_TabletExternallyReparented.md @@ -0,0 +1,36 @@ +--- +title: TabletExternallyReparented +series: vtctldclient +--- +## vtctldclient TabletExternallyReparented + +Updates the topology record for the tablet's shard to acknowledge that an external tool made this tablet the primary. + +### Synopsis + +Updates the topology record for the tablet's shard to acknowledge that an external tool made this tablet the primary. + +See the Reparenting guide for more information: https://vitess.io/docs/user-guides/configuration-advanced/reparenting/#external-reparenting. + + +``` +vtctldclient TabletExternallyReparented +``` + +### Options + +``` + -h, --help help for TabletExternallyReparented +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateCellInfo.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateCellInfo.md new file mode 100644 index 000000000..2663c2af1 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateCellInfo.md @@ -0,0 +1,37 @@ +--- +title: UpdateCellInfo +series: vtctldclient +--- +## vtctldclient UpdateCellInfo + +Updates the content of a CellInfo with the provided parameters, creating the CellInfo if it does not exist. + +### Synopsis + +Updates the content of a CellInfo with the provided parameters, creating the CellInfo if it does not exist. + +If a value is empty, it is ignored. + +``` +vtctldclient UpdateCellInfo [--root ] [--server-address ] +``` + +### Options + +``` + -h, --help help for UpdateCellInfo + -r, --root string The root path the topology server will use for this cell. + -a, --server-address string The address the topology server will connect to for this cell. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateCellsAlias.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateCellsAlias.md new file mode 100644 index 000000000..1f4d30a5b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateCellsAlias.md @@ -0,0 +1,34 @@ +--- +title: UpdateCellsAlias +series: vtctldclient +--- +## vtctldclient UpdateCellsAlias + +Updates the content of a CellsAlias with the provided parameters, creating the CellsAlias if it does not exist. + +### Synopsis + +Updates the content of a CellsAlias with the provided parameters, creating the CellsAlias if it does not exist. + +``` +vtctldclient UpdateCellsAlias [--cells [--cells ...]] +``` + +### Options + +``` + -c, --cells strings The list of cell names that are members of this alias. + -h, --help help for UpdateCellsAlias +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateThrottlerConfig.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateThrottlerConfig.md new file mode 100644 index 000000000..6492e9276 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_UpdateThrottlerConfig.md @@ -0,0 +1,40 @@ +--- +title: UpdateThrottlerConfig +series: vtctldclient +--- +## vtctldclient UpdateThrottlerConfig + +Update the tablet throttler configuration for all tablets in the given keyspace (across all cells) + +``` +vtctldclient UpdateThrottlerConfig [--enable|--disable] [--threshold=] [--custom-query=] [--check-as-check-self|--check-as-check-shard] [--throttle-app|unthrottle-app=] [--throttle-app-ratio=] [--throttle-app-duration=] +``` + +### Options + +``` + --check-as-check-self /throttler/check requests behave as is /throttler/check-self was called + --check-as-check-shard use standard behavior for /throttler/check requests + --custom-query string custom throttler check query + --disable Disable the throttler + --enable Enable the throttler + -h, --help help for UpdateThrottlerConfig + --threshold float threshold for the either default check (replication lag seconds) or custom check + --throttle-app string an app name to throttle + --throttle-app-duration duration duration after which throttled app rule expires (app specififed in --throttled-app) (default 1h0m0s) + --throttle-app-exempt exempt this app from being at all throttled. WARNING: use with extreme care, as this is likely to push metrics beyond the throttler's threshold, and starve other apps + --throttle-app-ratio float ratio to throttle app (app specififed in --throttled-app) (default 1) + --unthrottle-app string an app name to unthrottle +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/_index.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/_index.md new file mode 100644 index 000000000..8a9a1ac5c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/_index.md @@ -0,0 +1,39 @@ +--- +title: VDiff +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient VDiff + +Perform commands related to diffing tables involved in a VReplication workflow between the source and target. + +### Synopsis + +VDiff commands: create, resume, show, stop, and delete. +See the --help output for each command for more details. + +### Options + +``` + --format string The format of the output; supported formats are: text,json. (default "text") + -h, --help help for VDiff + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. +* [vtctldclient VDiff create](./vtctldclient_vdiff_create/) - Create and run a VDiff to compare the tables involved in a VReplication workflow between the source and target. +* [vtctldclient VDiff delete](./vtctldclient_vdiff_delete/) - Delete VDiffs. +* [vtctldclient VDiff resume](./vtctldclient_vdiff_resume/) - Resume a VDiff. +* [vtctldclient VDiff show](./vtctldclient_vdiff_show/) - Show the status of a VDiff. +* [vtctldclient VDiff stop](./vtctldclient_vdiff_stop/) - Stop a running VDiff. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_create.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_create.md new file mode 100644 index 000000000..b8b62788d --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_create.md @@ -0,0 +1,54 @@ +--- +title: VDiff create +series: vtctldclient +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtctldclient VDiff create + +Create and run a VDiff to compare the tables involved in a VReplication workflow between the source and target. + +``` +vtctldclient VDiff create +``` + +### Examples + +``` +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace customer +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace customer create b3f59678-5241-11ee-be56-0242ac120002 +``` + +### Options + +``` + --auto-retry Should this vdiff automatically retry and continue in case of recoverable errors. (default true) + --debug-query Adds a mysql query to the report that can be used for further debugging. + --filtered-replication-wait-time duration Specifies the maximum time to wait, in seconds, for replication to catch up when syncing tablet streams. (default 30s) + -h, --help help for create + --limit uint32 Max rows to stop comparing after. (default 4294967295) + --max-extra-rows-to-compare uint32 If there are collation differences between the source and target, you can have rows that are identical but simply returned in a different order from MySQL. We will do a second pass to compare the rows for any actual differences in this case and this flag allows you to control the resources used for this operation. (default 1000) + --only-pks When reporting missing rows, only show primary keys in the report. + --source-cells strings The source cell(s) to compare from; default is any available cell. + --tables strings Only run vdiff for these tables in the workflow. + --tablet-types strings Tablet types to use on the source and target. + --tablet-types-in-preference-order When performing source tablet selection, look for candidates in the type order as they are listed in the tablet-types flag. (default true) + --target-cells strings The target cell(s) to compare with; default is any available cell. + --update-table-stats Update the table statistics, using ANALYZE TABLE, on each table involved in the VDiff during initialization. This will ensure that progress estimates are as accurate as possible -- but it does involve locks and can potentially impact query processing on the target keyspace. + --wait When creating or resuming a vdiff, wait for it to finish before exiting. + --wait-update-interval duration When waiting on a vdiff to finish, check and display the current status this often. (default 1m0s) +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient VDiff](../) - Perform commands related to diffing tables involved in a VReplication workflow between the source and target. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_delete.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_delete.md new file mode 100644 index 000000000..7159bb695 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_delete.md @@ -0,0 +1,40 @@ +--- +title: VDiff delete +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient VDiff delete + +Delete VDiffs. + +``` +vtctldclient VDiff delete +``` + +### Examples + +``` +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace delete a037a9e2-5628-11ee-8c99-0242ac120002 +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace delete all +``` + +### Options + +``` + -h, --help help for delete +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient VDiff](../) - Perform commands related to diffing tables involved in a VReplication workflow between the source and target. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_resume.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_resume.md new file mode 100644 index 000000000..8be8d36f0 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_resume.md @@ -0,0 +1,39 @@ +--- +title: VDiff resume +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient VDiff resume + +Resume a VDiff. + +``` +vtctldclient VDiff resume +``` + +### Examples + +``` +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace resume a037a9e2-5628-11ee-8c99-0242ac120002 +``` + +### Options + +``` + -h, --help help for resume +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient VDiff](../) - Perform commands related to diffing tables involved in a VReplication workflow between the source and target. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_show.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_show.md new file mode 100644 index 000000000..a8290a2e4 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_show.md @@ -0,0 +1,42 @@ +--- +title: VDiff show +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient VDiff show + +Show the status of a VDiff. + +``` +vtctldclient VDiff show +``` + +### Examples + +``` +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace show last +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace show a037a9e2-5628-11ee-8c99-0242ac120002 +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace show all +``` + +### Options + +``` + -h, --help help for show + --verbose Show verbose output in summaries +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient VDiff](../) - Perform commands related to diffing tables involved in a VReplication workflow between the source and target. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_stop.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_stop.md new file mode 100644 index 000000000..6d3fff0fc --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_VDiff/vtctldclient_VDiff_stop.md @@ -0,0 +1,39 @@ +--- +title: VDiff stop +series: vtctldclient +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vtctldclient VDiff stop + +Stop a running VDiff. + +``` +vtctldclient VDiff stop +``` + +### Examples + +``` +vtctldclient --server localhost:15999 vdiff --workflow commerce2customer --target-keyspace stop a037a9e2-5628-11ee-8c99-0242ac120002 +``` + +### Options + +``` + -h, --help help for stop +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --format string The format of the output; supported formats are: text,json. (default "text") + --server string server to use for connection (required) + --target-keyspace string Target keyspace for this workflow. + -w, --workflow string The workflow you want to perform the command on. +``` + +### SEE ALSO + +* [vtctldclient VDiff](../) - Perform commands related to diffing tables involved in a VReplication workflow between the source and target. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Validate.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Validate.md new file mode 100644 index 000000000..49b50244a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Validate.md @@ -0,0 +1,30 @@ +--- +title: Validate +series: vtctldclient +--- +## vtctldclient Validate + +Validates that all nodes reachable from the global replication graph, as well as all tablets in discoverable cells, are consistent. + +``` +vtctldclient Validate [--ping-tablets] +``` + +### Options + +``` + -h, --help help for Validate + -p, --ping-tablets Indicates whether all tablets should be pinged during the validation process. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateKeyspace.md new file mode 100644 index 000000000..84d702d94 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateKeyspace.md @@ -0,0 +1,30 @@ +--- +title: ValidateKeyspace +series: vtctldclient +--- +## vtctldclient ValidateKeyspace + +Validates that all nodes reachable from the specified keyspace are consistent. + +``` +vtctldclient ValidateKeyspace [--ping-tablets] +``` + +### Options + +``` + -h, --help help for ValidateKeyspace + -p, --ping-tablets Indicates whether all tablets should be pinged during the validation process. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateSchemaKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateSchemaKeyspace.md new file mode 100644 index 000000000..3905c312c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateSchemaKeyspace.md @@ -0,0 +1,33 @@ +--- +title: ValidateSchemaKeyspace +series: vtctldclient +--- +## vtctldclient ValidateSchemaKeyspace + +Validates that the schema on the primary tablet for shard 0 matches the schema on all other tablets in the keyspace. + +``` +vtctldclient ValidateSchemaKeyspace [--exclude-tables=] [--include-views] [--skip-no-primary] [--include-vschema] +``` + +### Options + +``` + --exclude-tables strings Tables to exclude during schema comparison. + -h, --help help for ValidateSchemaKeyspace + --include-views Includes views in compared schemas. + --include-vschema Includes VSchema validation in validation results. + --skip-no-primary Skips validation on whether or not a primary exists in shards. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateShard.md new file mode 100644 index 000000000..21047cef1 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateShard.md @@ -0,0 +1,30 @@ +--- +title: ValidateShard +series: vtctldclient +--- +## vtctldclient ValidateShard + +Validates that all nodes reachable from the specified shard are consistent. + +``` +vtctldclient ValidateShard [--ping-tablets] +``` + +### Options + +``` + -h, --help help for ValidateShard + -p, --ping-tablets Indicates whether all tablets should be pinged during the validation process. +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateVersionKeyspace.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateVersionKeyspace.md new file mode 100644 index 000000000..cc3a4ccef --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateVersionKeyspace.md @@ -0,0 +1,29 @@ +--- +title: ValidateVersionKeyspace +series: vtctldclient +--- +## vtctldclient ValidateVersionKeyspace + +Validates that the version on the primary tablet of shard 0 matches all of the other tablets in the keyspace. + +``` +vtctldclient ValidateVersionKeyspace +``` + +### Options + +``` + -h, --help help for ValidateVersionKeyspace +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateVersionShard.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateVersionShard.md new file mode 100644 index 000000000..67e0635bc --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_ValidateVersionShard.md @@ -0,0 +1,29 @@ +--- +title: ValidateVersionShard +series: vtctldclient +--- +## vtctldclient ValidateVersionShard + +Validates that the version on the primary matches all of the replicas. + +``` +vtctldclient ValidateVersionShard +``` + +### Options + +``` + -h, --help help for ValidateVersionShard +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/_index.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/_index.md new file mode 100644 index 000000000..f10b8243d --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/_index.md @@ -0,0 +1,41 @@ +--- +title: Workflow +series: vtctldclient +--- +## vtctldclient Workflow + +Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + +### Synopsis + +Workflow commands: List, Show, Start, Stop, Update, and Delete. +See the --help output for each command for more details. + +``` +vtctldclient Workflow --keyspace [command] [command-flags] +``` + +### Options + +``` + -h, --help help for Workflow + -k, --keyspace string Keyspace context for the workflow (required). +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient](../) - Executes a cluster management command on the remote vtctld server. +* [vtctldclient Workflow delete](./vtctldclient_workflow_delete/) - Delete a VReplication workflow. +* [vtctldclient Workflow list](./vtctldclient_workflow_list/) - List the VReplication workflows in the given keyspace. +* [vtctldclient Workflow show](./vtctldclient_workflow_show/) - Show the details for a VReplication workflow. +* [vtctldclient Workflow start](./vtctldclient_workflow_start/) - Start a VReplication workflow. +* [vtctldclient Workflow stop](./vtctldclient_workflow_stop/) - Stop a VReplication workflow. +* [vtctldclient Workflow update](./vtctldclient_workflow_update/) - Update the configuration parameters for a VReplication workflow. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_delete.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_delete.md new file mode 100644 index 000000000..740620f8b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_delete.md @@ -0,0 +1,39 @@ +--- +title: Workflow delete +series: vtctldclient +--- +## vtctldclient Workflow delete + +Delete a VReplication workflow. + +``` +vtctldclient Workflow delete +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer delete --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for delete + --keep-data Keep the partially copied table data from the workflow in the target keyspace. + --keep-routing-rules Keep the routing rules created for the workflow. + -w, --workflow string The workflow you want to delete (required). +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required). + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_list.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_list.md new file mode 100644 index 000000000..f320d0ec7 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_list.md @@ -0,0 +1,36 @@ +--- +title: Workflow list +series: vtctldclient +--- +## vtctldclient Workflow list + +List the VReplication workflows in the given keyspace. + +``` +vtctldclient Workflow list +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer list +``` + +### Options + +``` + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required). + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_show.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_show.md new file mode 100644 index 000000000..b932110c8 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_show.md @@ -0,0 +1,37 @@ +--- +title: Workflow show +series: vtctldclient +--- +## vtctldclient Workflow show + +Show the details for a VReplication workflow. + +``` +vtctldclient Workflow show +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer show --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for show + -w, --workflow string The workflow you want the details for (required). +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required). + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_start.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_start.md new file mode 100644 index 000000000..10f3678c7 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_start.md @@ -0,0 +1,36 @@ +--- +title: Workflow start +series: vtctldclient +--- +## vtctldclient Workflow start + +Start a VReplication workflow. + +``` +vtctldclient Workflow start +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer start --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for start +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required). + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_stop.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_stop.md new file mode 100644 index 000000000..309a0e0bf --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_stop.md @@ -0,0 +1,36 @@ +--- +title: Workflow stop +series: vtctldclient +--- +## vtctldclient Workflow stop + +Stop a VReplication workflow. + +``` +vtctldclient Workflow stop +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer stop --workflow commerce2customer +``` + +### Options + +``` + -h, --help help for stop +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required). + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_update.md b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_update.md new file mode 100644 index 000000000..b7af017fa --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtctldclient/vtctldclient_Workflow/vtctldclient_Workflow_update.md @@ -0,0 +1,41 @@ +--- +title: Workflow update +series: vtctldclient +--- +## vtctldclient Workflow update + +Update the configuration parameters for a VReplication workflow. + +``` +vtctldclient Workflow update +``` + +### Examples + +``` +vtctldclient --server localhost:15999 workflow --keyspace customer update --workflow commerce2customer --cells zone1 --cells zone2 -c "zone3,zone4" -c zone5 +``` + +### Options + +``` + -c, --cells strings New Cell(s) or CellAlias(es) (comma-separated) to replicate from. + -h, --help help for update + --on-ddl string New instruction on what to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE. + -t, --tablet-types strings New source tablet types to replicate from (e.g. PRIMARY,REPLICA,RDONLY). + --tablet-types-in-order When performing source tablet selection, look for candidates in the type order as they are listed in the tablet-types flag. (default true) + -w, --workflow string The workflow you want to update (required). +``` + +### Options inherited from parent commands + +``` + --action_timeout duration timeout for the total command (default 1h0m0s) + -k, --keyspace string Keyspace context for the workflow (required). + --server string server to use for connection (required) +``` + +### SEE ALSO + +* [vtctldclient Workflow](../) - Administer VReplication workflows (Reshard, MoveTables, etc) in the given keyspace. + diff --git a/content/en/docs/19.0/reference/programs/vtexplain.md b/content/en/docs/19.0/reference/programs/vtexplain.md new file mode 100644 index 000000000..3fc3667de --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtexplain.md @@ -0,0 +1,72 @@ +--- +title: vtexplain +aliases: ['/docs/reference/vtexplain/'] +--- + +`vtexplain` is a command line tool which provides information on how Vitess plans to execute a particular query. It can +be used to validate queries for compatibility with Vitess. + +For a user guide that describes how to use the `vtexplain` tool to explain how Vitess executes a particular SQL +statement, see [Analyzing a SQL statement](../../../user-guides/sql/vtexplain/). + +## Example Usage + +Explain how Vitess will execute the query `SELECT * FROM users` using the VSchema contained in `vschemas.json` and the +database schema `schema.sql`: + +```bash +vtexplain -- --vschema-file vschema.json --schema-file schema.sql --sql "SELECT * FROM users" +``` + +Explain how the example will execute on 128 shards using Row-based replication: + +```bash +vtexplain -- -shards 128 --vschema-file vschema.json --schema-file schema.sql --replication-mode "ROW" --output-mode text --sql "INSERT INTO users (user_id, name) VALUES(1, 'john')" +``` + +## Options + +The following parameters apply to `mysqlctl`: + +| Name | Type | Definition | +|:-----------------------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------| +| --dbname | string | Optional database target to override normal routing | +| --execution-mode | string | The execution mode to simulate -- must be set to multi, legacy-autocommit, or twopc (default "multi") | +| --ks-shard-map | string | JSON map of keyspace name -> shard name -> ShardReference object. The inner map is the same as the output of FindAllShardsInKeyspace | +| --ks-shard-map-file | string | File containing json blob of keyspace name -> shard name -> ShardReference object | +| --mysql_server_version | string | MySQL server version to advertise. (default "8.0.30-Vitess") | +| --normalize | boolean | Whether to enable vtgate normalization | +| --output-mode | string | Output in human-friendly text or json (default "text") | +| --planner-version | string | Sets the default planner to use. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right | +| --replication-mode | string | The replication mode to simulate -- must be set to either ROW or STATEMENT (default "ROW") | +| --schema | string | The SQL table schema | +| --schema-file | string | Identifies the file that contains the SQL table schema | +| --shards | int | Number of shards per keyspace. Passing --ks-shard-map/--ks-shard-map-file causes this flag to be ignored. (default 2) | +| --sql | string | A list of semicolon-delimited SQL commands to analyze | +| --sql-file | string | Identifies the file that contains the SQL commands to analyze | +| --vschema | string | Identifies the VTGate routing schema | +| --vschema-file | string | Identifies the VTGate routing schema file | + +
+ +Please note that `-ks-shard-map` and `ks-shard-map-file` will supercede `--shards`. +If you attempt to `vtexplain` on a keyspace that is included in the keyspace shard map, the shards as defined in the +mapping will be used and `--shards` will be ignored. + +## Limitations + +### The VSchema must use a keyspace name. + +VTExplain requires a keyspace name for each keyspace in an input VSchema: + +``` +"keyspace_name": { + "_comment": "Keyspace definition goes here." +} +``` + +If no keyspace name is present, VTExplain will return the following error: + +``` +ERROR: initVtgateExecutor: json: cannot unmarshal bool into Go value of type map[string]json.RawMessage +``` diff --git a/content/en/docs/19.0/reference/programs/vtgate/_index.md b/content/en/docs/19.0/reference/programs/vtgate/_index.md new file mode 100644 index 000000000..3419eddf1 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtgate/_index.md @@ -0,0 +1,254 @@ +--- +title: vtgate +series: vtgate +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtgate + +VTGate is a stateless proxy responsible for accepting requests from applications and routing them to the appropriate tablet server(s) for query execution. It speaks both the MySQL Protocol and a gRPC protocol. + +### Synopsis + +VTGate is a stateless proxy responsible for accepting requests from applications and routing them to the appropriate tablet server(s) for query execution. It speaks both the MySQL Protocol and a gRPC protocol. + +### Key Options + +* `--srv_topo_cache_ttl`: There may be instances where you will need to increase the cached TTL from the default of 1 second to a higher number: + * You may want to increase this option if you see that your topo leader goes down and keeps your queries waiting for a few seconds. + +``` +vtgate [flags] +``` + +### Examples + +``` +vtgate \ + --topo_implementation etcd2 \ + --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global \ + --log_dir $VTDATAROOT/tmp \ + --port 15001 \ + --grpc_port 15991 \ + --mysql_server_port 15306 \ + --cell test \ + --cells_to_watch test \ + --tablet_types_to_wait PRIMARY,REPLICA \ + --service_map 'grpc-vtgateservice' \ + --pid_file $VTDATAROOT/tmp/vtgate.pid \ + --mysql_auth_server_impl none +``` + +### Options + +``` + --allow-kill-statement Allows the execution of kill statement + --allowed_tablet_types strings Specifies the tablet types this vtgate is allowed to route queries to. Should be provided as a comma-separated set of tablet types. + --alsologtostderr log to standard error as well as files + --buffer_drain_concurrency int Maximum number of requests retried simultaneously. More concurrency will increase the load on the PRIMARY vttablet when draining the buffer. (default 1) + --buffer_keyspace_shards string If not empty, limit buffering to these entries (comma separated). Entry format: keyspace or keyspace/shard. Requires --enable_buffer=true. + --buffer_max_failover_duration duration Stop buffering completely if a failover takes longer than this duration. (default 20s) + --buffer_min_time_between_failovers duration Minimum time between the end of a failover and the start of the next one (tracked per shard). Faster consecutive failovers will not trigger buffering. (default 1m0s) + --buffer_size int Maximum number of buffered requests in flight (across all ongoing failovers). (default 1000) + --buffer_window duration Duration for how long a request should be buffered at most. (default 10s) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --cell string cell to use + --cells_to_watch string comma-separated list of cells for watching tablets + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consul_auth_static_file string JSON File to read the topos/tokens from. + --datadog-agent-host string host to send spans to. if empty, no tracing will be done + --datadog-agent-port string port to send spans to. if empty, no tracing will be done + --dbddl_plugin string controls how to handle CREATE/DROP DATABASE. use it if you are using your own database provisioning service (default "fail") + --ddl_strategy string Set default strategy for DDL statements. Override with @@ddl_strategy session variable (default "direct") + --default_tablet_type topodatapb.TabletType The default tablet type to set for queries, when one is not explicitly selected. (default PRIMARY) + -d, --dir string output directory to write documentation (default "doc") + --discovery_high_replication_lag_minimum_serving duration Threshold above which replication lag is considered too high when applying the min_number_serving_vttablets flag. (default 2h0m0s) + --discovery_low_replication_lag duration Threshold below which replication lag is considered low enough to be healthy. (default 30s) + --emit_stats If set, emit stats to push-based monitoring and stats backends + --enable-partial-keyspace-migration (Experimental) Follow shard routing rules: enable only while migrating a keyspace shard by shard. See documentation on Partial MoveTables for more. (default false) + --enable-views Enable views support in vtgate. + --enable_buffer Enable buffering (stalling) of primary traffic during failovers. + --enable_buffer_dry_run Detect and log failover events, but do not actually buffer requests. + --enable_direct_ddl Allow users to submit direct DDL statements (default true) + --enable_online_ddl Allow users to submit, review and control Online DDL (default true) + --enable_set_var This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections (default true) + --enable_system_settings This will enable the system settings to be changed per session at the database connection level (default true) + --foreign_key_mode string This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow, disallow (default "allow") + --gate_query_cache_memory int gate server query cache size in bytes, maximum amount of memory to be cached. vtgate analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 33554432) + --gateway_initial_tablet_timeout duration At startup, the tabletGateway will wait up to this duration to get at least one tablet per keyspace/shard/tablet type (default 30s) + --grpc-send-session-in-streaming If set, will send the session as last packet in streaming api to support transactions in streaming + --grpc-use-effective-groups If set, and SSL is not used, will set the immediate caller's security groups from the effective caller id's groups. + --grpc-use-static-authentication-callerid If set, will set the immediate caller id to the username authenticated by the static auth plugin. + --grpc_auth_mode string Which auth plugin implementation to use (eg: static) + --grpc_auth_mtls_allowed_substrings string List of substrings of at least one of the client certificate names (separated by colon). + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_auth_static_password_file string JSON File to read the users/passwords from. + --grpc_ca string server CA to use for gRPC connections, requires TLS, and enforces client certificate check + --grpc_cert string server certificate to use for gRPC connections, requires grpc_key, enables TLS + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_crl string path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake + --grpc_enable_optional_tls enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_key string server private key to use for gRPC connections, requires grpc_cert, enables TLS + --grpc_max_connection_age duration Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) + --grpc_max_connection_age_grace duration Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_port int Port to listen on for gRPC calls. If zero, do not listen. + --grpc_prometheus Enable gRPC monitoring with Prometheus. + --grpc_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --grpc_server_initial_conn_window_size int gRPC server initial connection window size + --grpc_server_initial_window_size int gRPC server initial window size + --grpc_server_keepalive_enforcement_policy_min_time duration gRPC server minimum keepalive time (default 10s) + --grpc_server_keepalive_enforcement_policy_permit_without_stream gRPC server permit client keepalive pings even when there are no active streams (RPCs) + --grpc_use_effective_callerid If set, and SSL is not used, will set the immediate caller id from the effective caller id's principal. + --healthcheck_retry_delay duration health check retry delay (default 2ms) + --healthcheck_timeout duration the health check timeout period (default 1m0s) + -h, --help help for docgen + --jaeger-agent-host string host and port to send spans to. if empty, no tracing will be done + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --keyspaces_to_watch strings Specifies which keyspaces this vtgate should have access to while routing queries or accessing the vschema. + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --legacy_replication_lag_algorithm Use the legacy algorithm when selecting vttablets for serving. (default true) + --lock-timeout duration Maximum time for which a shard/keyspace lock can be acquired for (default 45s) + --lock_heartbeat_time duration If there is lock function used. This will keep the lock connection active by using this heartbeat (default 5s) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_queries_to_file string Enable query logging to the specified file + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --max_memory_rows int Maximum number of rows that will be held in memory for intermediate results as well as the final result. (default 300000) + --max_payload_size int The threshold for query payloads in bytes. A payload greater than this threshold will result in a failure to handle the query. + --message_stream_grace_period duration the amount of time to give for a vttablet to resume if it ends a message stream, usually because of a reparent. (default 30s) + --min_number_serving_vttablets int The minimum number of vttablets for each replicating tablet_type (e.g. replica, rdonly) that will be continue to be used even with replication lag above discovery_low_replication_lag, but still below discovery_high_replication_lag_minimum_serving. (default 2) + --mysql-server-keepalive-period duration TCP period between keep-alives + --mysql-server-pool-conn-read-buffers If set, the server will pool incoming connection read buffers + --mysql_allow_clear_text_without_tls If set, the server will allow the use of a clear text password over non-SSL connections. + --mysql_auth_server_impl string Which auth server implementation to use. Options: none, ldap, clientcert, static, vault. (default "static") + --mysql_auth_server_static_file string JSON File to read the users/passwords from. + --mysql_auth_server_static_string string JSON representation of the users/passwords config. + --mysql_auth_static_reload_interval duration Ticker to reload credentials + --mysql_auth_vault_addr string URL to Vault server + --mysql_auth_vault_path string Vault path to vtgate credentials JSON blob, e.g.: secret/data/prod/vtgatecreds + --mysql_auth_vault_role_mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --mysql_auth_vault_role_secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --mysql_auth_vault_roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --mysql_auth_vault_timeout duration Timeout for vault API operations (default 10s) + --mysql_auth_vault_tls_ca string Path to CA PEM for validating Vault server certificate + --mysql_auth_vault_tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --mysql_auth_vault_ttl duration How long to cache vtgate credentials from the Vault server (default 30m0s) + --mysql_clientcert_auth_method string client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") + --mysql_default_workload string Default session workload (OLTP, OLAP, DBA) (default "OLTP") + --mysql_ldap_auth_config_file string JSON File from which to read LDAP server config. + --mysql_ldap_auth_config_string string JSON representation of LDAP server config. + --mysql_ldap_auth_method string client-side authentication method to use. Supported values: mysql_clear_password, dialog. (default "mysql_clear_password") + --mysql_server_bind_address string Binds on this address when listening to MySQL binary protocol. Useful to restrict listening to 'localhost' only for instance. + --mysql_server_flush_delay duration Delay after which buffered response will be flushed to the client. (default 100ms) + --mysql_server_port int If set, also listen for MySQL binary protocol connections on this port. (default -1) + --mysql_server_query_timeout duration mysql query timeout + --mysql_server_read_timeout duration connection read timeout + --mysql_server_require_secure_transport Reject insecure connections but only if mysql_server_ssl_cert and mysql_server_ssl_key are provided + --mysql_server_socket_path string This option specifies the Unix socket file to use when listening for local connections. By default it will be empty and it won't listen to a unix socket + --mysql_server_ssl_ca string Path to ssl CA for mysql server plugin SSL. If specified, server will require and validate client certs. + --mysql_server_ssl_cert string Path to the ssl cert for mysql server plugin SSL + --mysql_server_ssl_crl string Path to ssl CRL for mysql server plugin SSL + --mysql_server_ssl_key string Path to ssl key for mysql server plugin SSL + --mysql_server_ssl_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --mysql_server_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysql_server_write_timeout duration connection write timeout + --mysql_slow_connect_warn_threshold duration Warn if it takes more than the given threshold for a mysql connection to establish + --mysql_tcp_version string Select tcp, tcp4, or tcp6 to control the socket type. (default "tcp") + --no_scatter when set to true, the planner will fail instead of producing a plan that includes scatter queries + --normalize_queries Rewrite queries with bind vars. Turn this off if the app itself sends normalized queries with bind vars. (default true) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --opentsdb_uri string URI of opentsdb /api/put method + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --planner-version string Sets the default planner to use when the session has not changed it. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right + --port int port for the server + --pprof strings enable profiling + --proxy_protocol Enable HAProxy PROXY protocol on MySQL listener socket + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --query-timeout int Sets the default query timeout (in ms). Can be overridden by session variable (query_timeout) or comment directive (QUERY_TIMEOUT_MS) + --querylog-buffer-size int Maximum number of buffered query logs before throttling log output (default 10) + --querylog-filter-tag string string that must be present in the query for it to be logged; if using a value as the tag, you need to disable query normalization + --querylog-format string format for query logs ("text" or "json") (default "text") + --querylog-row-threshold uint Number of rows a query has to return or affect before being logged; not useful for streaming queries. 0 means all queries will be logged. + --redact-debug-ui-queries redact full queries and bind variables from debug UI + --remote_operation_timeout duration time to wait for a remote operation (default 15s) + --retry-count int retry count (default 2) + --schema_change_signal Enable the schema tracker; requires queryserver-config-schema-change-signal to be enabled on the underlying vttablets for this to work (default true) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --sql-max-length-errors int truncate queries in error logs to the given length (default unlimited) + --sql-max-length-ui int truncate queries in debug UIs to the given length (default 512) (default 512) + --srv_topo_cache_refresh duration how frequently to refresh the topology for cached entries (default 1s) + --srv_topo_cache_ttl duration how long to use cached entries for topology (default 1s) + --srv_topo_timeout duration topo server timeout (default 5s) + --stats_backend string The name of the registered push-based monitoring/stats backend to use + --stats_combine_dimensions string List of dimensions to be combined into a single "all" value in exported stats vars + --stats_common_tags strings Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 + --stats_drop_variables string Variables to be dropped from the list of exported variables. + --stats_emit_period duration Interval between emitting stats to all registered backends (default 1m0s) + --statsd_address string Address for statsd client + --statsd_sample_rate float Sample rate for statsd metrics (default 1) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --stream_buffer_size int the number of bytes sent from vtgate for each stream call. It's recommended to keep this value in sync with vttablet's query-server-config-stream-buffer-size. (default 32768) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_filters strings Specifies a comma-separated list of 'keyspace|shard_name or keyrange' values to filter the tablets to watch. + --tablet_grpc_ca string the server ca to use to validate servers when connecting + --tablet_grpc_cert string the cert to use to connect + --tablet_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_grpc_key string the key to use to connect + --tablet_grpc_server_name string the server name to use to validate server certificate + --tablet_protocol string Protocol to use to make queryservice RPCs to vttablets. (default "grpc") + --tablet_refresh_interval duration Tablet refresh interval. (default 1m0s) + --tablet_refresh_known_tablets Whether to reload the tablet's address/port map from topo in case they change. (default true) + --tablet_types_to_wait strings Wait till connected for specified tablet types during Gateway initialization. Should be provided as a comma-separated set of tablet types. + --tablet_url_template string Format string describing debug tablet url formatting. See getTabletDebugURL() for how to customize this. (default "http://{{.GetTabletHostPort}}") + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) + --topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server + --topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS + --topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS + --topo_global_root string the path of the global topology data in the global topology server + --topo_global_server_address string the address of the global topology server + --topo_implementation string the topology implementation to use + --topo_read_concurrency int Concurrency of topo reads. (default 32) + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --tracer string tracing service to use (default "noop") + --tracing-enable-logging whether to enable logging in the tracing service + --tracing-sampling-rate float sampling rate for the probabilistic jaeger sampler (default 0.1) + --tracing-sampling-type string sampling strategy to use for jaeger. possible values are 'const', 'probabilistic', 'rateLimiting', or 'remote' (default "const") + --transaction_mode string SINGLE: disallow multi-db transactions, MULTI: allow multi-db transactions with best effort commit, TWOPC: allow multi-db transactions with 2pc commit (default "MULTI") + --truncate-error-len int truncate errors sent to client if they are longer than this value (0 means do not truncate) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --vschema_ddl_authorized_users string List of users authorized to execute vschema ddl operations, or '%' to allow all users. + --vtgate-config-terse-errors prevent bind vars from escaping in returned errors + --warn_memory_rows int Warning threshold for in-memory results. A row count higher than this amount will cause the VtGateWarnings.ResultsExceeded counter to be incremented. (default 30000) + --warn_payload_size int The warning threshold for query payloads in bytes. A payload greater than this threshold will cause the VtGateWarnings.WarnPayloadSizeExceeded counter to be incremented. + --warn_sharded_only If any features that are only available in unsharded mode are used, query execution warnings will be added to the session +``` + diff --git a/content/en/docs/19.0/reference/programs/vtgateclienttest/_index.md b/content/en/docs/19.0/reference/programs/vtgateclienttest/_index.md new file mode 100644 index 000000000..b25168be6 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtgateclienttest/_index.md @@ -0,0 +1,77 @@ +--- +title: vtgateclienttest +series: vtgateclienttest +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtgateclienttest + +vtgateclienttest is a chain of vtgateservice.VTGateService implementations, each one being responsible for one test scenario. + +``` +vtgateclienttest [flags] +``` + +### Options + +``` + --alsologtostderr log to standard error as well as files + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --default_tablet_type topodatapb.TabletType The default tablet type to set for queries, when one is not explicitly selected. (default PRIMARY) + --grpc_auth_mode string Which auth plugin implementation to use (eg: static) + --grpc_auth_mtls_allowed_substrings string List of substrings of at least one of the client certificate names (separated by colon). + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_auth_static_password_file string JSON File to read the users/passwords from. + --grpc_ca string server CA to use for gRPC connections, requires TLS, and enforces client certificate check + --grpc_cert string server certificate to use for gRPC connections, requires grpc_key, enables TLS + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_crl string path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake + --grpc_enable_optional_tls enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_key string server private key to use for gRPC connections, requires grpc_cert, enables TLS + --grpc_max_connection_age duration Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) + --grpc_max_connection_age_grace duration Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_port int Port to listen on for gRPC calls. If zero, do not listen. + --grpc_prometheus Enable gRPC monitoring with Prometheus. + --grpc_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --grpc_server_initial_conn_window_size int gRPC server initial connection window size + --grpc_server_initial_window_size int gRPC server initial window size + --grpc_server_keepalive_enforcement_policy_min_time duration gRPC server minimum keepalive time (default 10s) + --grpc_server_keepalive_enforcement_policy_permit_without_stream gRPC server permit client keepalive pings even when there are no active streams (RPCs) + -h, --help help for vtgateclienttest + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --port int port for the server + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --vschema_ddl_authorized_users string List of users authorized to execute vschema ddl operations, or '%' to allow all users. +``` + diff --git a/content/en/docs/19.0/reference/programs/vtorc/_index.md b/content/en/docs/19.0/reference/programs/vtorc/_index.md new file mode 100644 index 000000000..158514447 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vtorc/_index.md @@ -0,0 +1,124 @@ +--- +title: vtorc +series: vtorc +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vtorc + +VTOrc is the automated fault detection and repair tool in Vitess. + +``` +vtorc [flags] +``` + +### Examples + +``` +vtorc \ + --topo_implementation etcd2 \ + --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global \ + --log_dir $VTDATAROOT/tmp \ + --port 15000 \ + --recovery-period-block-duration "10m" \ + --instance-poll-time "1s" \ + --topo-information-refresh-duration "30s" \ + --alsologtostderr +``` + +### Options + +``` + --allow-emergency-reparent Whether VTOrc should be allowed to run emergency reparent operation when it detects a dead primary (default true) + --alsologtostderr log to standard error as well as files + --audit-file-location string File location where the audit logs are to be stored + --audit-purge-duration duration Duration for which audit logs are held before being purged. Should be in multiples of days (default 168h0m0s) + --audit-to-backend Whether to store the audit log in the VTOrc database + --audit-to-syslog Whether to store the audit log in the syslog + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --change-tablets-with-errant-gtid-to-drained Whether VTOrc should be changing the type of tablets with errant GTIDs to DRAINED + --clusters_to_watch strings Comma-separated list of keyspaces or keyspace/shards that this instance will monitor and repair. Defaults to all clusters in the topology. Example: "ks1,ks2/-80" + --config string config file name + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consul_auth_static_file string JSON File to read the topos/tokens from. + --emit_stats If set, emit stats to push-based monitoring and stats backends + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_prometheus Enable gRPC monitoring with Prometheus. + -h, --help help for vtorc + --instance-poll-time duration Timer duration on which VTOrc refreshes MySQL information (default 5s) + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --lock-timeout duration Maximum time for which a shard/keyspace lock can be acquired for (default 45s) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --port int port for the server + --pprof strings enable profiling + --prevent-cross-cell-failover Prevent VTOrc from promoting a primary in a different cell than the current primary in case of a failover + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --reasonable-replication-lag duration Maximum replication lag on replicas which is deemed to be acceptable (default 10s) + --recovery-period-block-duration duration Duration for which a new recovery is blocked on an instance after running a recovery (default 30s) + --recovery-poll-duration duration Timer duration on which VTOrc polls its database to run a recovery (default 1s) + --remote_operation_timeout duration time to wait for a remote operation (default 15s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --shutdown_wait_time duration Maximum time to wait for VTOrc to release all the locks that it is holding before shutting down on SIGTERM (default 30s) + --snapshot-topology-interval duration Timer duration on which VTOrc takes a snapshot of the current MySQL information it has in the database. Should be in multiple of hours + --sqlite-data-file string SQLite Datafile to use as VTOrc's database (default "file::memory:?mode=memory&cache=shared") + --stats_backend string The name of the registered push-based monitoring/stats backend to use + --stats_combine_dimensions string List of dimensions to be combined into a single "all" value in exported stats vars + --stats_common_tags strings Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 + --stats_drop_variables string Variables to be dropped from the list of exported variables. + --stats_emit_period duration Interval between emitting stats to all registered backends (default 1m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_manager_grpc_ca string the server ca to use to validate servers when connecting + --tablet_manager_grpc_cert string the cert to use to connect + --tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) + --tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100) + --tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_manager_grpc_key string the key to use to connect + --tablet_manager_grpc_server_name string the server name to use to validate server certificate + --tablet_manager_protocol string Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") + --topo-information-refresh-duration duration Timer duration on which VTOrc refreshes the keyspace and vttablet records from the topology server (default 15s) + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) + --topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server + --topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS + --topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS + --topo_global_root string the path of the global topology data in the global topology server + --topo_global_server_address string the address of the global topology server + --topo_implementation string the topology implementation to use + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --wait-replicas-timeout duration Duration for which to wait for replica's to respond when issuing RPCs (default 30s) +``` + diff --git a/content/en/docs/19.0/reference/programs/vttablet/_index.md b/content/en/docs/19.0/reference/programs/vttablet/_index.md new file mode 100644 index 000000000..034ef7fbb --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttablet/_index.md @@ -0,0 +1,450 @@ +--- +title: vttablet +series: vttablet +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vttablet + +The VTTablet server controls a running MySQL server. + +### Synopsis + +The VTTablet server _controls_ a running MySQL server. VTTablet supports two primary types of deployments: + +* Managed MySQL (most common) +* External MySQL + +In addition to these deployment types, a partially managed VTTablet is also possible by setting `--disable_active_reparents`. + +### Managed MySQL + +In this mode, Vitess actively manages MySQL. + +### External MySQL. + +In this mode, an external MySQL can be used such as AWS RDS, AWS Aurora, Google CloudSQL; or just an existing (vanilla) MySQL installation. + +See "Unmanaged Tablet" for the full guide. + +Even if a MySQL is external, you can still make vttablet perform some management functions. They are as follows: + +* `--disable_active_reparents`: If this flag is set, then any reparent or replica commands will not be allowed. These are InitShardPrimary, PlannedReparentShard, EmergencyReparentShard, and ReparentTablet. In this mode, you should use the TabletExternallyReparented command to inform vitess of the current primary. +* `--replication_connect_retry`: This value is give to mysql when it connects a replica to the primary as the retry duration parameter. +* `--enable_replication_reporter`: If this flag is set, then vttablet will transmit replica lag related information to the vtgates, which will allow it to balance load better. Additionally, enabling this will also cause vttablet to restart replication if it was stopped. However, it will do this only if `--disable_active_reparents` was not turned on. +* `--heartbeat_enable` and `--heartbeat_interval duration`: cause vttablet to write heartbeats to the sidecar database. This information is also used by the replication reporter to assess replica lag. + + +``` +vttablet [flags] +``` + +### Examples + +``` + +vttablet \ + --topo_implementation etcd2 \ + --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/ \ + --tablet-path $alias \ + --init_keyspace $keyspace \ + --init_shard $shard \ + --init_tablet_type $tablet_type \ + --port $port \ + --grpc_port $grpc_port \ + --service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updatestream' + +`$alias` needs to be of the form: `-id`, and the cell should match one of the local cells that was created in the topology. The id can be left padded with zeroes: `cell-100` and `cell-000000100` are synonymous. +``` + +### Options + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --azblob_backup_account_key_file string Path to a file containing the Azure Storage account key; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_KEY will be used as the key itself (NOT a file path). + --azblob_backup_account_name string Azure Storage Account name for backups; if this flag is unset, the environment variable VT_AZBLOB_ACCOUNT_NAME will be used. + --azblob_backup_buffer_size int The memory buffer size to use in bytes, per file or stripe, when streaming to Azure Blob Service. (default 104857600) + --azblob_backup_container_name string Azure Blob Container Name. + --azblob_backup_parallelism int Azure Blob operation parallelism (requires extra memory when increased -- a multiple of azblob_backup_buffer_size). (default 1) + --azblob_backup_storage_root string Root prefix for all backup-related Azure Blobs; this should exclude both initial and trailing '/' (e.g. just 'a/b' not '/a/b/'). + --backup_engine_implementation string Specifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin") + --backup_storage_block_size int if backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000) + --backup_storage_compress if set, the backup files will be compressed. (default true) + --backup_storage_implementation string Which backup storage implementation to use for creating and restoring backups. + --backup_storage_number_blocks int if backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, in parallel, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression. (default 2) + --binlog_host string PITR restore parameter: hostname/IP of binlog server. + --binlog_password string PITR restore parameter: password of binlog server. + --binlog_player_grpc_ca string the server ca to use to validate servers when connecting + --binlog_player_grpc_cert string the cert to use to connect + --binlog_player_grpc_crl string the server crl to use to validate server certificates when connecting + --binlog_player_grpc_key string the key to use to connect + --binlog_player_grpc_server_name string the server name to use to validate server certificate + --binlog_player_protocol string the protocol to download binlogs from a vttablet (default "grpc") + --binlog_port int PITR restore parameter: port of binlog server. + --binlog_ssl_ca string PITR restore parameter: Filename containing TLS CA certificate to verify binlog server TLS certificate against. + --binlog_ssl_cert string PITR restore parameter: Filename containing mTLS client certificate to present to binlog server as authentication. + --binlog_ssl_key string PITR restore parameter: Filename containing mTLS client private key for use in binlog server authentication. + --binlog_ssl_server_name string PITR restore parameter: TLS server name (common name) to verify against for the binlog server we are connecting to (If not set: use the hostname or IP supplied in --binlog_host). + --binlog_user string PITR restore parameter: username of binlog server. + --builtinbackup-file-read-buffer-size uint read files using an IO buffer of this many bytes. Golang defaults are used when set to 0. + --builtinbackup-file-write-buffer-size uint write files using an IO buffer of this many bytes. Golang defaults are used when set to 0. (default 2097152) + --builtinbackup_mysqld_timeout duration how long to wait for mysqld to shutdown at the start of the backup. (default 10m0s) + --builtinbackup_progress duration how often to send progress updates when backing up large files. (default 5s) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --ceph_backup_storage_config string Path to JSON config file for ceph backup storage. (default "ceph_backup_config.json") + --compression-engine-name string compressor engine used for compression. (default "pargzip") + --compression-level int what level to pass to the compressor. (default 1) + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consolidator-stream-query-size int Configure the stream consolidator query size in bytes. Setting to 0 disables the stream consolidator. (default 2097152) + --consolidator-stream-total-size int Configure the stream consolidator total size in bytes. Setting to 0 disables the stream consolidator. (default 134217728) + --consul_auth_static_file string JSON File to read the topos/tokens from. + --datadog-agent-host string host to send spans to. if empty, no tracing will be done + --datadog-agent-port string port to send spans to. if empty, no tracing will be done + --db-credentials-file string db credentials file; send SIGHUP to reload this file + --db-credentials-server string db credentials server type ('file' - file implementation; 'vault' - HashiCorp Vault implementation) (default "file") + --db-credentials-vault-addr string URL to Vault server + --db-credentials-vault-path string Vault path to credentials JSON blob, e.g.: secret/data/prod/dbcreds + --db-credentials-vault-role-mountpoint string Vault AppRole mountpoint; can also be passed using VAULT_MOUNTPOINT environment variable (default "approle") + --db-credentials-vault-role-secretidfile string Path to file containing Vault AppRole secret_id; can also be passed using VAULT_SECRETID environment variable + --db-credentials-vault-roleid string Vault AppRole id; can also be passed using VAULT_ROLEID environment variable + --db-credentials-vault-timeout duration Timeout for vault API operations (default 10s) + --db-credentials-vault-tls-ca string Path to CA PEM for validating Vault server certificate + --db-credentials-vault-tokenfile string Path to file containing Vault auth token; token can also be passed using VAULT_TOKEN environment variable + --db-credentials-vault-ttl duration How long to cache DB credentials from the Vault server (default 30m0s) + --db_allprivs_password string db allprivs password + --db_allprivs_use_ssl Set this flag to false to make the allprivs connection to not use ssl (default true) + --db_allprivs_user string db allprivs user userKey (default "vt_allprivs") + --db_app_password string db app password + --db_app_use_ssl Set this flag to false to make the app connection to not use ssl (default true) + --db_app_user string db app user userKey (default "vt_app") + --db_appdebug_password string db appdebug password + --db_appdebug_use_ssl Set this flag to false to make the appdebug connection to not use ssl (default true) + --db_appdebug_user string db appdebug user userKey (default "vt_appdebug") + --db_charset string Character set used for this tablet. (default "utf8mb4") + --db_conn_query_info enable parsing and processing of QUERY_OK info fields + --db_connect_timeout_ms int connection timeout to mysqld in milliseconds (0 for no timeout) + --db_dba_password string db dba password + --db_dba_use_ssl Set this flag to false to make the dba connection to not use ssl (default true) + --db_dba_user string db dba user userKey (default "vt_dba") + --db_erepl_password string db erepl password + --db_erepl_use_ssl Set this flag to false to make the erepl connection to not use ssl (default true) + --db_erepl_user string db erepl user userKey (default "vt_erepl") + --db_filtered_password string db filtered password + --db_filtered_use_ssl Set this flag to false to make the filtered connection to not use ssl (default true) + --db_filtered_user string db filtered user userKey (default "vt_filtered") + --db_flags uint Flag values as defined by MySQL. + --db_flavor string Flavor overrid. Valid value is FilePos. + --db_host string The host name for the tcp connection. + --db_port int tcp port + --db_repl_password string db repl password + --db_repl_use_ssl Set this flag to false to make the repl connection to not use ssl (default true) + --db_repl_user string db repl user userKey (default "vt_repl") + --db_server_name string server name of the DB we are connecting to. + --db_socket string The unix socket to connect on. If this is specified, host and port will not be used. + --db_ssl_ca string connection ssl ca + --db_ssl_ca_path string connection ssl ca path + --db_ssl_cert string connection ssl certificate + --db_ssl_key string connection ssl key + --db_ssl_mode SslMode SSL mode to connect with. One of disabled, preferred, required, verify_ca & verify_identity. + --db_tls_min_version string Configures the minimal TLS version negotiated when SSL is enabled. Defaults to TLSv1.2. Options: TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --degraded_threshold duration replication lag after which a replica is considered degraded (default 30s) + --disable_active_reparents if set, do not allow active reparents. Use this to protect a cluster using external reparents. + --emit_stats If set, emit stats to push-based monitoring and stats backends + --enable-consolidator Synonym to -enable_consolidator (default true) + --enable-consolidator-replicas Synonym to -enable_consolidator_replicas + --enable-per-workload-table-metrics If true, query counts and query error metrics include a label that identifies the workload + --enable-tx-throttler Synonym to -enable_tx_throttler + --enable_consolidator This option enables the query consolidator. (default true) + --enable_consolidator_replicas This option enables the query consolidator only on replicas. + --enable_hot_row_protection If true, incoming transactions for the same row (range) will be queued and cannot consume all txpool slots. + --enable_hot_row_protection_dry_run If true, hot row protection is not enforced but logs if transactions would have been queued. + --enable_replication_reporter Use polling to track replication lag. + --enable_transaction_limit If true, limit on number of transactions open at the same time will be enforced for all users. User trying to open a new transaction after exhausting their limit will receive an error immediately, regardless of whether there are available slots or not. + --enable_transaction_limit_dry_run If true, limit on number of transactions open at the same time will be tracked for all users, but not enforced. + --enable_tx_throttler If true replication-lag-based throttling on transactions will be enabled. + --enforce-tableacl-config if this flag is true, vttablet will fail to start if a valid tableacl config does not exist + --enforce_strict_trans_tables If true, vttablet requires MySQL to run with STRICT_TRANS_TABLES or STRICT_ALL_TABLES on. It is recommended to not turn this flag off. Otherwise MySQL may alter your supplied values before saving them to the database. (default true) + --external-compressor string command with arguments to use when compressing a backup. + --external-compressor-extension string extension to use when using an external compressor. + --external-decompressor string command with arguments to use when decompressing a backup. + --file_backup_storage_root string Root directory for the file backup storage. + --filecustomrules string file based custom rule path + --filecustomrules_watch set up a watch on the target file and reload query rules when it changes + --gc_check_interval duration Interval between garbage collection checks (default 1h0m0s) + --gc_purge_check_interval duration Interval between purge discovery checks (default 1m0s) + --gcs_backup_storage_bucket string Google Cloud Storage bucket to use for backups. + --gcs_backup_storage_root string Root prefix for all backup-related object names. + --gh-ost-path string override default gh-ost binary full path + --grpc_auth_mode string Which auth plugin implementation to use (eg: static) + --grpc_auth_mtls_allowed_substrings string List of substrings of at least one of the client certificate names (separated by colon). + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_auth_static_password_file string JSON File to read the users/passwords from. + --grpc_ca string server CA to use for gRPC connections, requires TLS, and enforces client certificate check + --grpc_cert string server certificate to use for gRPC connections, requires grpc_key, enables TLS + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_crl string path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake + --grpc_enable_optional_tls enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_key string server private key to use for gRPC connections, requires grpc_cert, enables TLS + --grpc_max_connection_age duration Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) + --grpc_max_connection_age_grace duration Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_port int Port to listen on for gRPC calls. If zero, do not listen. + --grpc_prometheus Enable gRPC monitoring with Prometheus. + --grpc_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --grpc_server_initial_conn_window_size int gRPC server initial connection window size + --grpc_server_initial_window_size int gRPC server initial window size + --grpc_server_keepalive_enforcement_policy_min_time duration gRPC server minimum keepalive time (default 10s) + --grpc_server_keepalive_enforcement_policy_permit_without_stream gRPC server permit client keepalive pings even when there are no active streams (RPCs) + --health_check_interval duration Interval between health checks (default 20s) + --heartbeat_enable If true, vttablet records (if master) or checks (if replica) the current time of a replication heartbeat in the sidecar database's heartbeat table. The result is used to inform the serving state of the vttablet via healthchecks. + --heartbeat_interval duration How frequently to read and write replication heartbeat. (default 1s) + --heartbeat_on_demand_duration duration If non-zero, heartbeats are only written upon consumer request, and only run for up to given duration following the request. Frequent requests can keep the heartbeat running consistently; when requests are infrequent heartbeat may completely stop between requests + -h, --help help for vttablet + --hot_row_protection_concurrent_transactions int Number of concurrent transactions let through to the txpool/MySQL for the same hot row. Should be > 1 to have enough 'ready' transactions in MySQL and benefit from a pipelining effect. (default 5) + --hot_row_protection_max_global_queue_size int Global queue limit across all row (ranges). Useful to prevent that the queue can grow unbounded. (default 1000) + --hot_row_protection_max_queue_size int Maximum number of BeginExecute RPCs which will be queued for the same row (range). (default 20) + --init_db_name_override string (init parameter) override the name of the db used by vttablet. Without this flag, the db name defaults to vt_ + --init_keyspace string (init parameter) keyspace to use for this tablet + --init_shard string (init parameter) shard to use for this tablet + --init_tablet_type string (init parameter) the tablet type to use for this tablet. + --init_tags StringMap (init parameter) comma separated list of key:value pairs used to tag the tablet + --init_timeout duration (init parameter) timeout to use for the init phase. (default 1m0s) + --jaeger-agent-host string host and port to send spans to. if empty, no tracing will be done + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --lock-timeout duration Maximum time for which a shard/keyspace lock can be acquired for (default 45s) + --lock_tables_timeout duration How long to keep the table locked before timing out (default 1m0s) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_queries Enable query logging to syslog. + --log_queries_to_file string Enable query logging to the specified file + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --manifest-external-decompressor string command with arguments to store in the backup manifest when compressing a backup with an external compression engine. + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --max_concurrent_online_ddl int Maximum number of online DDL changes that may run concurrently (default 256) + --migration_check_interval duration Interval between migration checks (default 1m0s) + --mycnf-file string path to my.cnf, if reading all config params from there + --mycnf_bin_log_path string mysql binlog path + --mycnf_data_dir string data directory for mysql + --mycnf_error_log_path string mysql error log path + --mycnf_general_log_path string mysql general log path + --mycnf_innodb_data_home_dir string Innodb data home directory + --mycnf_innodb_log_group_home_dir string Innodb log group home directory + --mycnf_master_info_file string mysql master.info file + --mycnf_mysql_port int port mysql is listening on + --mycnf_pid_file string mysql pid file + --mycnf_relay_log_index_path string mysql relay log index path + --mycnf_relay_log_info_path string mysql relay log info path + --mycnf_relay_log_path string mysql relay log path + --mycnf_secure_file_priv string mysql path for loading secure files + --mycnf_server_id int mysql server id of the server (if specified, mycnf-file will be ignored) + --mycnf_slow_log_path string mysql slow query log path + --mycnf_socket_file string mysql socket file + --mycnf_tmp_dir string mysql tmp directory + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --opentsdb_uri string URI of opentsdb /api/put method + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --pitr_gtid_lookup_timeout duration PITR restore parameter: timeout for fetching gtid from timestamp. (default 1m0s) + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --port int port for the server + --pprof strings enable profiling + --pt-osc-path string override default pt-online-schema-change binary full path + --publish_retry_interval duration how long vttablet waits to retry publishing the tablet record (default 30s) + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --query-log-stream-handler string URL handler for streaming queries log (default "/debug/querylog") + --querylog-filter-tag string string that must be present in the query for it to be logged; if using a value as the tag, you need to disable query normalization + --querylog-format string format for query logs ("text" or "json") (default "text") + --querylog-row-threshold uint Number of rows a query has to return or affect before being logged; not useful for streaming queries. 0 means all queries will be logged. + --queryserver-config-acl-exempt-acl string an acl that exempt from table acl checking (this acl is free to access any vitess tables). + --queryserver-config-annotate-queries prefix queries to MySQL backend with comment indicating vtgate principal (user) and target tablet type + --queryserver-config-enable-table-acl-dry-run If this flag is enabled, tabletserver will emit monitoring metrics and let the request pass regardless of table acl check results + --queryserver-config-idle-timeout duration query server idle timeout (in seconds), vttablet manages various mysql connection pools. This config means if a connection has not been used in given idle timeout, this connection will be removed from pool. This effectively manages number of connection objects and optimize the pool performance. (default 30m0s) + --queryserver-config-max-result-size int query server max result size, maximum number of rows allowed to return from vttablet for non-streaming queries. (default 10000) + --queryserver-config-message-postpone-cap int query server message postpone cap is the maximum number of messages that can be postponed at any given time. Set this number to substantially lower than transaction cap, so that the transaction pool isn't exhausted by the message subsystem. (default 4) + --queryserver-config-olap-transaction-timeout duration query server transaction timeout (in seconds), after which a transaction in an OLAP session will be killed (default 30s) + --queryserver-config-passthrough-dmls query server pass through all dml statements without rewriting + --queryserver-config-pool-conn-max-lifetime duration query server connection max lifetime (in seconds), vttablet manages various mysql connection pools. This config means if a connection has lived at least this long, it connection will be removed from pool upon the next time it is returned to the pool. (default 0s) + --queryserver-config-pool-size int query server read pool size, connection pool is used by regular queries (non streaming, not in a transaction) (default 16) + --queryserver-config-query-cache-memory int query server query cache size in bytes, maximum amount of memory to be used for caching. vttablet analyzes every incoming query and generate a query plan, these plans are being cached in a lru cache. This config controls the capacity of the lru cache. (default 33554432) + --queryserver-config-query-pool-timeout duration query server query pool timeout (in seconds), it is how long vttablet waits for a connection from the query pool. If set to 0 (default) then the overall query timeout is used instead. (default 0s) + --queryserver-config-query-pool-waiter-cap int query server query pool waiter limit, this is the maximum number of queries that can be queued waiting to get a connection (default 5000) + --queryserver-config-query-timeout duration query server query timeout (in seconds), this is the query timeout in vttablet side. If a query takes more than this timeout, it will be killed. (default 30s) + --queryserver-config-schema-change-signal query server schema signal, will signal connected vtgates that schema has changed whenever this is detected. VTGates will need to have -schema_change_signal enabled for this to work (default true) + --queryserver-config-schema-reload-time duration query server schema reload time, how often vttablet reloads schemas from underlying MySQL instance in seconds. vttablet keeps table schemas in its own memory and periodically refreshes it from MySQL. This config controls the reload time. (default 30m0s) + --queryserver-config-stream-buffer-size int query server stream buffer size, the maximum number of bytes sent from vttablet for each stream call. It's recommended to keep this value in sync with vtgate's stream_buffer_size. (default 32768) + --queryserver-config-stream-pool-size int query server stream connection pool size, stream pool is used by stream queries: queries that return results to client in a streaming fashion (default 200) + --queryserver-config-stream-pool-timeout duration query server stream pool timeout (in seconds), it is how long vttablet waits for a connection from the stream pool. If set to 0 (default) then there is no timeout. (default 0s) + --queryserver-config-stream-pool-waiter-cap int query server stream pool waiter limit, this is the maximum number of streaming queries that can be queued waiting to get a connection + --queryserver-config-strict-table-acl only allow queries that pass table acl checks + --queryserver-config-terse-errors prevent bind vars from escaping in client error messages + --queryserver-config-transaction-cap int query server transaction cap is the maximum number of transactions allowed to happen at any given point of a time for a single vttablet. E.g. by setting transaction cap to 100, there are at most 100 transactions will be processed by a vttablet and the 101th transaction will be blocked (and fail if it cannot get connection within specified timeout) (default 20) + --queryserver-config-transaction-timeout duration query server transaction timeout (in seconds), a transaction will be killed if it takes longer than this value (default 30s) + --queryserver-config-truncate-error-len int truncate errors sent to client if they are longer than this value (0 means do not truncate) + --queryserver-config-txpool-timeout duration query server transaction pool timeout, it is how long vttablet waits if tx pool is full (default 1s) + --queryserver-config-txpool-waiter-cap int query server transaction pool waiter limit, this is the maximum number of transactions that can be queued waiting to get a connection (default 5000) + --queryserver-config-warn-result-size int query server result size warning threshold, warn if number of rows returned from vttablet for non-streaming queries exceeds this + --queryserver-enable-settings-pool Enable pooling of connections with modified system settings (default true) + --queryserver-enable-views Enable views support in vttablet. + --queryserver_enable_online_ddl Enable online DDL. (default true) + --redact-debug-ui-queries redact full queries and bind variables from debug UI + --relay_log_max_items int Maximum number of rows for VReplication target buffering. (default 5000) + --relay_log_max_size int Maximum buffer size (in bytes) for VReplication target buffering. If single rows are larger than this, a single row is buffered at a time. (default 250000) + --remote_operation_timeout duration time to wait for a remote operation (default 15s) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --restore-to-pos string (init incremental restore parameter) if set, run a point in time recovery that ends with the given position. This will attempt to use one full backup followed by zero or more incremental backups + --restore-to-timestamp string (init incremental restore parameter) if set, run a point in time recovery that restores up to the given timestamp, if possible. Given timestamp in RFC3339 format. Example: '2006-01-02T15:04:05Z07:00' + --restore_concurrency int (init restore parameter) how many concurrent files to restore at once (default 4) + --restore_from_backup (init restore parameter) will check BackupStorage for a recent backup at startup and start there + --restore_from_backup_ts string (init restore parameter) if set, restore the latest backup taken at or before this timestamp. Example: '2021-04-29.133050' + --retain_online_ddl_tables duration How long should vttablet keep an old migrated table before purging it (default 24h0m0s) + --s3_backup_aws_endpoint string endpoint of the S3 backend (region must be provided). + --s3_backup_aws_region string AWS region to use. (default "us-east-1") + --s3_backup_aws_retries int AWS request retries. (default -1) + --s3_backup_force_path_style force the s3 path style. + --s3_backup_log_level string determine the S3 loglevel to use from LogOff, LogDebug, LogDebugWithSigning, LogDebugWithHTTPBody, LogDebugWithRequestRetries, LogDebugWithRequestErrors. (default "LogOff") + --s3_backup_server_side_encryption string server-side encryption algorithm (e.g., AES256, aws:kms, sse_c:/path/to/key/file). + --s3_backup_storage_bucket string S3 bucket to use for backups. + --s3_backup_storage_root string root prefix for all backup-related object names. + --s3_backup_tls_skip_verify_cert skip the 'certificate is valid' check for SSL connections. + --sanitize_log_messages Remove potentially sensitive information in tablet INFO, WARNING, and ERROR log messages such as query parameters. + --schema-change-reload-timeout duration query server schema change reload timeout, this is how long to wait for the signaled schema reload operation to complete before giving up (default 30s) + --schema-version-max-age-seconds int max age of schema version records to kept in memory by the vreplication historian + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --serving_state_grace_period duration how long to pause after broadcasting health to vtgate, before enforcing a new serving state + --shard_sync_retry_delay duration delay between retries of updates to keep the tablet and its shard record in sync (default 30s) + --shutdown_grace_period duration how long to wait (in seconds) for queries and transactions to complete during graceful shutdown. (default 0s) + --sql-max-length-errors int truncate queries in error logs to the given length (default unlimited) + --sql-max-length-ui int truncate queries in debug UIs to the given length (default 512) (default 512) + --srv_topo_cache_refresh duration how frequently to refresh the topology for cached entries (default 1s) + --srv_topo_cache_ttl duration how long to use cached entries for topology (default 1s) + --srv_topo_timeout duration topo server timeout (default 5s) + --stats_backend string The name of the registered push-based monitoring/stats backend to use + --stats_combine_dimensions string List of dimensions to be combined into a single "all" value in exported stats vars + --stats_common_tags strings Comma-separated list of common tags for the stats backend. It provides both label and values. Example: label1:value1,label2:value2 + --stats_drop_variables string Variables to be dropped from the list of exported variables. + --stats_emit_period duration Interval between emitting stats to all registered backends (default 1m0s) + --statsd_address string Address for statsd client + --statsd_sample_rate float Sample rate for statsd metrics (default 1) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --stream_health_buffer_size uint max streaming health entries to buffer per streaming health client (default 20) + --table-acl-config string path to table access checker config file; send SIGHUP to reload this file + --table-acl-config-reload-interval duration Ticker to reload ACLs. Duration flag, format e.g.: 30s. Default: do not reload + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --table_gc_lifecycle string States for a DROP TABLE garbage collection cycle. Default is 'hold,purge,evac,drop', use any subset ('drop' implcitly always included) (default "hold,purge,evac,drop") + --tablet-path string tablet alias + --tablet_config string YAML file config for tablet + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_grpc_ca string the server ca to use to validate servers when connecting + --tablet_grpc_cert string the cert to use to connect + --tablet_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_grpc_key string the key to use to connect + --tablet_grpc_server_name string the server name to use to validate server certificate + --tablet_hostname string if not empty, this hostname will be assumed instead of trying to resolve it + --tablet_manager_grpc_ca string the server ca to use to validate servers when connecting + --tablet_manager_grpc_cert string the cert to use to connect + --tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) + --tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100) + --tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_manager_grpc_key string the key to use to connect + --tablet_manager_grpc_server_name string the server name to use to validate server certificate + --tablet_manager_protocol string Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") + --tablet_protocol string Protocol to use to make queryservice RPCs to vttablets. (default "grpc") + --throttle_tablet_types string Comma separated VTTablet types to be considered by the throttler. default: 'replica'. example: 'replica,rdonly'. 'replica' aways implicitly included (default "replica") + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_etcd_lease_ttl int Lease TTL for locks and leader election. The client will use KeepAlive to keep the lease going. (default 30) + --topo_etcd_tls_ca string path to the ca to use to validate the server cert when connecting to the etcd topo server + --topo_etcd_tls_cert string path to the client cert to use to connect to the etcd topo server, requires topo_etcd_tls_key, enables TLS + --topo_etcd_tls_key string path to the client key to use to connect to the etcd topo server, enables TLS + --topo_global_root string the path of the global topology data in the global topology server + --topo_global_server_address string the address of the global topology server + --topo_implementation string the topology implementation to use + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --topocustomrule_cell string topo cell for customrules file. (default "global") + --topocustomrule_path string path for customrules file. Disabled if empty. + --tracer string tracing service to use (default "noop") + --tracing-enable-logging whether to enable logging in the tracing service + --tracing-sampling-rate float sampling rate for the probabilistic jaeger sampler (default 0.1) + --tracing-sampling-type string sampling strategy to use for jaeger. possible values are 'const', 'probabilistic', 'rateLimiting', or 'remote' (default "const") + --track_schema_versions When enabled, vttablet will store versions of schemas at each position that a DDL is applied and allow retrieval of the schema corresponding to a position + --transaction-log-stream-handler string URL handler for streaming transactions log (default "/debug/txlog") + --transaction_limit_by_component Include CallerID.component when considering who the user is for the purpose of transaction limit. + --transaction_limit_by_principal Include CallerID.principal when considering who the user is for the purpose of transaction limit. (default true) + --transaction_limit_by_subcomponent Include CallerID.subcomponent when considering who the user is for the purpose of transaction limit. + --transaction_limit_by_username Include VTGateCallerID.username when considering who the user is for the purpose of transaction limit. (default true) + --transaction_limit_per_user float Maximum number of transactions a single user is allowed to use at any time, represented as fraction of -transaction_cap. (default 0.4) + --twopc_abandon_age float time in seconds. Any unresolved transaction older than this time will be sent to the coordinator to be resolved. + --twopc_coordinator_address string address of the (VTGate) process(es) that will be used to notify of abandoned transactions. + --twopc_enable if the flag is on, 2pc is enabled. Other 2pc flags must be supplied. + --tx-throttler-config string Synonym to -tx_throttler_config (default "target_replication_lag_sec:2 max_replication_lag_sec:10 initial_rate:100 max_increase:1 emergency_decrease:0.5 min_duration_between_increases_sec:40 max_duration_between_increases_sec:62 min_duration_between_decreases_sec:20 spread_backlog_across_sec:20 age_bad_rate_after_sec:180 bad_rate_increase:0.1 max_rate_approach_threshold:0.9") + --tx-throttler-default-priority int Default priority assigned to queries that lack priority information (default 100) + --tx-throttler-dry-run If present, the transaction throttler only records metrics about requests received and throttled, but does not actually throttle any requests. + --tx-throttler-healthcheck-cells strings Synonym to -tx_throttler_healthcheck_cells + --tx-throttler-tablet-types strings A comma-separated list of tablet types. Only tablets of this type are monitored for replication lag by the transaction throttler. Supported types are replica and/or rdonly. (default replica) + --tx-throttler-topo-refresh-interval duration The rate that the transaction throttler will refresh the topology to find cells. (default 5m0s) + --tx_throttler_config string The configuration of the transaction throttler as a text-formatted throttlerdata.Configuration protocol buffer message. (default "target_replication_lag_sec:2 max_replication_lag_sec:10 initial_rate:100 max_increase:1 emergency_decrease:0.5 min_duration_between_increases_sec:40 max_duration_between_increases_sec:62 min_duration_between_decreases_sec:20 spread_backlog_across_sec:20 age_bad_rate_after_sec:180 bad_rate_increase:0.1 max_rate_approach_threshold:0.9") + --tx_throttler_healthcheck_cells strings A comma-separated list of cells. Only tabletservers running in these cells will be monitored for replication lag by the transaction throttler. + --unhealthy_threshold duration replication lag after which a replica is considered unhealthy (default 2h0m0s) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --vreplication-parallel-insert-workers int Number of parallel insertion workers to use during copy phase. Set <= 1 to disable parallelism, or > 1 to enable concurrent insertion during copy phase. (default 1) + --vreplication_copy_phase_duration duration Duration for each copy phase loop (before running the next catchup: default 1h) (default 1h0m0s) + --vreplication_copy_phase_max_innodb_history_list_length int The maximum InnoDB transaction history that can exist on a vstreamer (source) before starting another round of copying rows. This helps to limit the impact on the source tablet. (default 1000000) + --vreplication_copy_phase_max_mysql_replication_lag int The maximum MySQL replication lag (in seconds) that can exist on a vstreamer (source) before starting another round of copying rows. This helps to limit the impact on the source tablet. (default 43200) + --vreplication_experimental_flags int (Bitmask) of experimental features in vreplication to enable (default 3) + --vreplication_healthcheck_retry_delay duration healthcheck retry delay (default 5s) + --vreplication_healthcheck_timeout duration healthcheck retry delay (default 1m0s) + --vreplication_healthcheck_topology_refresh duration refresh interval for re-reading the topology (default 30s) + --vreplication_heartbeat_update_interval int Frequency (in seconds, default 1, max 60) at which the time_updated column of a vreplication stream when idling (default 1) + --vreplication_max_time_to_retry_on_error duration stop automatically retrying when we've had consecutive failures with the same error for this long after the first occurrence + --vreplication_replica_lag_tolerance duration Replica lag threshold duration: once lag is below this we switch from copy phase to the replication (streaming) phase (default 1m0s) + --vreplication_retry_delay duration delay before retrying a failed workflow event in the replication phase (default 5s) + --vreplication_store_compressed_gtid Store compressed gtids in the pos column of the sidecar database's vreplication table + --vreplication_tablet_type string comma separated list of tablet types used as a source (default "in_order:REPLICA,PRIMARY") + --vstream-binlog-rotation-threshold int Byte size at which a VStreamer will attempt to rotate the source's open binary log before starting a GTID snapshot based stream (e.g. a ResultStreamer or RowStreamer) (default 67108864) + --vstream_dynamic_packet_size Enable dynamic packet sizing for VReplication. This will adjust the packet size during replication to improve performance. (default true) + --vstream_packet_size int Suggested packet size for VReplication streamer. This is used only as a recommendation. The actual packet size may be more or less than this amount. (default 250000) + --vtgate_protocol string how to talk to vtgate (default "grpc") + --vttablet_skip_buildinfo_tags string comma-separated list of buildinfo tags to skip from merging with --init_tags. each tag is either an exact match or a regular expression of the form '/regexp/'. (default "/.*/") + --wait_for_backup_interval duration (init restore parameter) if this is greater than 0, instead of starting up empty when no backups are found, keep checking at this interval for a backup to appear + --watch_replication_stream When enabled, vttablet will stream the MySQL replication stream from the local server, and use it to update schema when it sees a DDL. + --xbstream_restore_flags string Flags to pass to xbstream command during restore. These should be space separated and will be added to the end of the command. These need to match the ones used for backup e.g. --compress / --decompress, --encrypt / --decrypt + --xtrabackup_backup_flags string Flags to pass to backup command. These should be space separated and will be added to the end of the command + --xtrabackup_prepare_flags string Flags to pass to prepare command. These should be space separated and will be added to the end of the command + --xtrabackup_root_path string Directory location of the xtrabackup and xbstream executables, e.g., /usr/bin + --xtrabackup_stream_mode string Which mode to use if streaming, valid values are tar and xbstream. Please note that tar is not supported in XtraBackup 8.0 (default "tar") + --xtrabackup_stripe_block_size uint Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) + --xtrabackup_stripes uint If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression + --xtrabackup_user string User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. +``` + diff --git a/content/en/docs/19.0/reference/programs/vttestserver/_index.md b/content/en/docs/19.0/reference/programs/vttestserver/_index.md new file mode 100644 index 000000000..b36c41001 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttestserver/_index.md @@ -0,0 +1,172 @@ +--- +title: vttestserver +series: vttestserver +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## vttestserver + +vttestserver allows users to spawn a self-contained Vitess server for local testing/CI. + +``` +vttestserver [flags] +``` + +### Options + +``` + --alsologtostderr log to standard error as well as files + --app_idle_timeout duration Idle timeout for app connections (default 1m0s) + --app_pool_size int Size of the connection pool for app connections (default 40) + --backup_engine_implementation string Specifies which implementation to use for creating new backups (builtin or xtrabackup). Restores will always be done with whichever engine created a given backup. (default "builtin") + --backup_storage_block_size int if backup_storage_compress is true, backup_storage_block_size sets the byte size for each block while compressing (default is 250000). (default 250000) + --backup_storage_compress if set, the backup files will be compressed. (default true) + --backup_storage_number_blocks int if backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, in parallel, before the writer blocks, during compression (default is 2). It should be equal to the number of CPUs available for compression. (default 2) + --builtinbackup-file-read-buffer-size uint read files using an IO buffer of this many bytes. Golang defaults are used when set to 0. + --builtinbackup-file-write-buffer-size uint write files using an IO buffer of this many bytes. Golang defaults are used when set to 0. (default 2097152) + --builtinbackup_mysqld_timeout duration how long to wait for mysqld to shutdown at the start of the backup. (default 10m0s) + --builtinbackup_progress duration how often to send progress updates when backing up large files. (default 5s) + --catch-sigpipe catch and ignore SIGPIPE on stdout and stderr if specified + --cells strings Comma separated list of cells (default [test]) + --charset string MySQL charset (default "utf8mb4") + --compression-engine-name string compressor engine used for compression. (default "pargzip") + --compression-level int what level to pass to the compressor. (default 1) + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --consul_auth_static_file string JSON File to read the topos/tokens from. + --data_dir string Directory where the data files will be placed, defaults to a random directory under /vt/vtdataroot + --dba_idle_timeout duration Idle timeout for dba connections (default 1m0s) + --dba_pool_size int Size of the connection pool for dba connections (default 20) + --default_schema_dir string Default directory for initial schema files. If no schema is found in schema_dir, default to this location. + --disable_active_reparents if set, do not allow active reparents. Use this to protect a cluster using external reparents. + --enable_direct_ddl Allow users to submit direct DDL statements (default true) + --enable_online_ddl Allow users to submit, review and control Online DDL (default true) + --enable_system_settings This will enable the system settings to be changed per session at the database connection level (default true) + --external-compressor string command with arguments to use when compressing a backup. + --external-compressor-extension string extension to use when using an external compressor. + --external-decompressor string command with arguments to use when decompressing a backup. + --external_topo_global_root string the path of the global topology data in the global topology server for vtcombo process + --external_topo_global_server_address string the address of the global topology server for vtcombo process + --external_topo_implementation string the topology implementation to use for vtcombo process + --extra_my_cnf string extra files to add to the config, separated by ':' + --foreign_key_mode string This is to provide how to handle foreign key constraint in create/alter table. Valid values are: allow, disallow (default "allow") + --grpc_auth_mode string Which auth plugin implementation to use (eg: static) + --grpc_auth_mtls_allowed_substrings string List of substrings of at least one of the client certificate names (separated by colon). + --grpc_auth_static_client_creds string When using grpc_static_auth in the server, this file provides the credentials to use to authenticate with server. + --grpc_auth_static_password_file string JSON File to read the users/passwords from. + --grpc_ca string server CA to use for gRPC connections, requires TLS, and enforces client certificate check + --grpc_cert string server certificate to use for gRPC connections, requires grpc_key, enables TLS + --grpc_compression string Which protocol to use for compressing gRPC. Default: nothing. Supported: snappy + --grpc_crl string path to a certificate revocation list in PEM format, client certificates will be further verified against this file during TLS handshake + --grpc_enable_optional_tls enable optional TLS mode when a server accepts both TLS and plain-text connections on the same port + --grpc_enable_tracing Enable gRPC tracing. + --grpc_initial_conn_window_size int gRPC initial connection window size + --grpc_initial_window_size int gRPC initial window size + --grpc_keepalive_time duration After a duration of this time, if the client doesn't see any activity, it pings the server to see if the transport is still alive. (default 10s) + --grpc_keepalive_timeout duration After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. (default 10s) + --grpc_key string server private key to use for gRPC connections, requires grpc_cert, enables TLS + --grpc_max_connection_age duration Maximum age of a client connection before GoAway is sent. (default 2562047h47m16.854775807s) + --grpc_max_connection_age_grace duration Additional grace period after grpc_max_connection_age, after which connections are forcibly closed. (default 2562047h47m16.854775807s) + --grpc_max_message_size int Maximum allowed RPC message size. Larger messages will be rejected by gRPC with the error 'exceeding the max size'. (default 16777216) + --grpc_port int Port to listen on for gRPC calls. If zero, do not listen. + --grpc_prometheus Enable gRPC monitoring with Prometheus. + --grpc_server_ca string path to server CA in PEM format, which will be combine with server cert, return full certificate chain to clients + --grpc_server_initial_conn_window_size int gRPC server initial connection window size + --grpc_server_initial_window_size int gRPC server initial window size + --grpc_server_keepalive_enforcement_policy_min_time duration gRPC server minimum keepalive time (default 10s) + --grpc_server_keepalive_enforcement_policy_permit_without_stream gRPC server permit client keepalive pings even when there are no active streams (RPCs) + -h, --help help for vttestserver + --initialize_with_random_data If this flag is each table-shard will be initialized with random data. See also the 'rng_seed' and 'min_shard_size' and 'max_shard_size' flags. + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --keyspaces strings Comma separated list of keyspaces (default [test_keyspace]) + --lameduck-period duration keep running at least this long after SIGTERM before stopping (default 50ms) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --manifest-external-decompressor string command with arguments to store in the backup manifest when compressing a backup with an external compression engine. + --max-stack-size int configure the maximum stack size in bytes (default 67108864) + --max_table_shard_size int The maximum number of initial rows in a table shard. Ignored if--initialize_with_random_data is false. The actual number is chosen randomly (default 10000) + --min_table_shard_size int The minimum number of initial rows in a table shard. Ignored if--initialize_with_random_data is false. The actual number is chosen randomly. (default 1000) + --mysql_bind_host string which host to bind vtgate mysql listener to (default "localhost") + --mysql_only If this flag is set only mysql is initialized. The rest of the vitess components are not started. Also, the output specifies the mysql unix socket instead of the vtgate port. + --mysql_server_version string MySQL server version to advertise. (default "8.0.30-Vitess") + --mysqlctl_mycnf_template string template file to use for generating the my.cnf file during server init + --mysqlctl_socket string socket file to use for remote mysqlctl actions (empty for local actions) + --null_probability float The probability to initialize a field with 'NULL' if --initialize_with_random_data is true. Only applies to fields that can contain NULL values. (default 0.1) + --num_shards strings Comma separated shard count (one per keyspace) (default [2]) + --onclose_timeout duration wait no more than this for OnClose handlers before stopping (default 10s) + --onterm_timeout duration wait no more than this for OnTermSync handlers before stopping (default 10s) + --persistent_mode If this flag is set, the MySQL data directory is not cleaned up when LocalCluster.TearDown() is called. This is useful for running vttestserver as a database container in local developer environments. Note that db migration files (--schema_dir option) and seeding of random data (--initialize_with_random_data option) will only run during cluster startup if the data directory does not already exist. Changes to VSchema are persisted across cluster restarts using a simple watcher if the --data_dir argument is specified. + --pid_file string If set, the process will write its pid to the named file, and delete it on graceful shutdown. + --planner-version string Sets the default planner to use when the session has not changed it. Valid values are: Gen4, Gen4Greedy, Gen4Left2Right + --pool_hostname_resolve_interval duration if set force an update to all hostnames and reconnect if changed, defaults to 0 (disabled) + --port int Port to use for vtcombo. If this is 0, a random port will be chosen. + --pprof strings enable profiling + --proto_topo string Define the fake cluster topology as a compact text format encoded vttest proto. See vttest.proto for more information. + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --queryserver-config-transaction-timeout float query server transaction timeout (in seconds), a transaction will be killed if it takes longer than this value + --rdonly_count int Rdonly tablets per shard (default 1) + --replica_count int Replica tablets per shard (includes primary) (default 2) + --replication_connect_retry duration how long to wait in between replica reconnect attempts. Only precise to the second. (default 10s) + --rng_seed int The random number generator seed to use when initializing with random data (see also --initialize_with_random_data). Multiple runs with the same seed will result with the same initial data. (default 123) + --schema_dir string Directory for initial schema files. Within this dir, there should be a subdir for each keyspace. Within each keyspace dir, each file is executed as SQL after the database is created on each shard. If the directory contains a vschema.json file, it will be used as the vschema for the V3 API. + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --service_map strings comma separated list of services to enable (or disable if prefixed with '-') Example: grpc-queryservice + --snapshot_file string A MySQL DB snapshot file + --sql-max-length-errors int truncate queries in error logs to the given length (default unlimited) + --sql-max-length-ui int truncate queries in debug UIs to the given length (default 512) (default 512) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --table-refresh-interval int interval in milliseconds to refresh tables in status page with refreshRequired class + --tablet_dir string The directory within the vtdataroot to store vttablet/mysql files. Defaults to being generated by the tablet uid. + --tablet_hostname string The hostname to use for the tablet otherwise it will be derived from OS' hostname (default "localhost") + --tablet_manager_grpc_ca string the server ca to use to validate servers when connecting + --tablet_manager_grpc_cert string the cert to use to connect + --tablet_manager_grpc_concurrency int concurrency to use to talk to a vttablet server for performance-sensitive RPCs (like ExecuteFetchAs{Dba,AllPrivs,App}) (default 8) + --tablet_manager_grpc_connpool_size int number of tablets to keep tmclient connections open to (default 100) + --tablet_manager_grpc_crl string the server crl to use to validate server certificates when connecting + --tablet_manager_grpc_key string the key to use to connect + --tablet_manager_grpc_server_name string the server name to use to validate server certificate + --tablet_manager_protocol string Protocol to use to make tabletmanager RPCs to vttablets. (default "grpc") + --tablet_refresh_interval duration Interval at which vtgate refreshes tablet information from topology server. (default 10s) + --topo_consul_lock_delay duration LockDelay for consul session. (default 15s) + --topo_consul_lock_session_checks string List of checks for consul session. (default "serfHealth") + --topo_consul_lock_session_ttl string TTL for consul session. + --topo_consul_watch_poll_duration duration time of the long poll for watch queries. (default 30s) + --topo_zk_auth_file string auth to use when connecting to the zk topo server, file contents should be :, e.g., digest:user:pass + --topo_zk_base_timeout duration zk base timeout (see zk.Connect) (default 30s) + --topo_zk_max_concurrency int maximum number of pending requests to send to a Zookeeper server. (default 64) + --topo_zk_tls_ca string the server ca to use to validate servers when connecting to the zk topo server + --topo_zk_tls_cert string the cert to use to connect to the zk topo server, requires topo_zk_tls_key, enables TLS + --topo_zk_tls_key string the key to use to connect to the zk topo server, enables TLS + --transaction_mode string Transaction mode MULTI (default), SINGLE or TWOPC (default "MULTI") + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --vschema_ddl_authorized_users string Comma separated list of users authorized to execute vschema ddl operations via vtgate + --vtctl_client_protocol string Protocol to use to talk to the vtctl server. (default "grpc") + --vtctld_grpc_ca string the server ca to use to validate servers when connecting + --vtctld_grpc_cert string the cert to use to connect + --vtctld_grpc_crl string the server crl to use to validate server certificates when connecting + --vtctld_grpc_key string the key to use to connect + --vtctld_grpc_server_name string the server name to use to validate server certificate + --vtgate_grpc_ca string the server ca to use to validate servers when connecting + --vtgate_grpc_cert string the cert to use to connect + --vtgate_grpc_crl string the server crl to use to validate server certificates when connecting + --vtgate_grpc_key string the key to use to connect + --vtgate_grpc_server_name string the server name to use to validate server certificate + --xbstream_restore_flags string Flags to pass to xbstream command during restore. These should be space separated and will be added to the end of the command. These need to match the ones used for backup e.g. --compress / --decompress, --encrypt / --decrypt + --xtrabackup_backup_flags string Flags to pass to backup command. These should be space separated and will be added to the end of the command + --xtrabackup_prepare_flags string Flags to pass to prepare command. These should be space separated and will be added to the end of the command + --xtrabackup_root_path string Directory location of the xtrabackup and xbstream executables, e.g., /usr/bin + --xtrabackup_stream_mode string Which mode to use if streaming, valid values are tar and xbstream. Please note that tar is not supported in XtraBackup 8.0 (default "tar") + --xtrabackup_stripe_block_size uint Size in bytes of each block that gets sent to a given stripe before rotating to the next stripe (default 102400) + --xtrabackup_stripes uint If greater than 0, use data striping across this many destination files to parallelize data transfer and decompression + --xtrabackup_user string User that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation. +``` + diff --git a/content/en/docs/19.0/reference/programs/vttlstest/_index.md b/content/en/docs/19.0/reference/programs/vttlstest/_index.md new file mode 100644 index 000000000..00068b07b --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttlstest/_index.md @@ -0,0 +1,28 @@ +--- +title: vttlstest +series: vttlstest +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vttlstest + +vttlstest is a tool for generating test certificates, keys, and related artifacts for TLS tests. + +### Synopsis + +vttlstest is a tool for generating test certificates, keys, and related artifacts for TLS tests. + +### Options + +``` + -h, --help help for vttlstest + --root string root directory for all artifacts (default ".") +``` + +### SEE ALSO + +* [vttlstest CreateCA](./vttlstest_createca/) - Create certificate authority +* [vttlstest CreateCRL](./vttlstest_createcrl/) - Create certificate revocation list +* [vttlstest CreateIntermediateCA](./vttlstest_createintermediateca/) - Create intermediate certificate authority +* [vttlstest CreateSignedCert](./vttlstest_createsignedcert/) - Create signed certificate +* [vttlstest RevokeCert](./vttlstest_revokecert/) - Revoke a certificate + diff --git a/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateCA.md b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateCA.md new file mode 100644 index 000000000..67dc8758a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateCA.md @@ -0,0 +1,39 @@ +--- +title: CreateCA +series: vttlstest +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vttlstest CreateCA + +Create certificate authority + +### Synopsis + +Create certificate authority + +``` +vttlstest CreateCA [--root ] +``` + +### Examples + +``` +CreateCA --root /tmp +``` + +### Options + +``` + -h, --help help for CreateCA +``` + +### Options inherited from parent commands + +``` + --root string root directory for all artifacts (default ".") +``` + +### SEE ALSO + +* [vttlstest](../) - vttlstest is a tool for generating test certificates, keys, and related artifacts for TLS tests. + diff --git a/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateCRL.md b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateCRL.md new file mode 100644 index 000000000..591c89fb3 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateCRL.md @@ -0,0 +1,39 @@ +--- +title: CreateCRL +series: vttlstest +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vttlstest CreateCRL + +Create certificate revocation list + +### Synopsis + +Create certificate revocation list + +``` +vttlstest CreateCRL [--root ] +``` + +### Examples + +``` +CreateCRL --root /tmp mail.mycoolsite.com +``` + +### Options + +``` + -h, --help help for CreateCRL +``` + +### Options inherited from parent commands + +``` + --root string root directory for all artifacts (default ".") +``` + +### SEE ALSO + +* [vttlstest](../) - vttlstest is a tool for generating test certificates, keys, and related artifacts for TLS tests. + diff --git a/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateIntermediateCA.md b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateIntermediateCA.md new file mode 100644 index 000000000..c575173ad --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateIntermediateCA.md @@ -0,0 +1,42 @@ +--- +title: CreateIntermediateCA +series: vttlstest +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vttlstest CreateIntermediateCA + +Create intermediate certificate authority + +### Synopsis + +Create intermediate certificate authority + +``` +vttlstest CreateIntermediateCA [--root ] [--parent ] [--serial ] [--common-name ] +``` + +### Examples + +``` +CreateIntermediateCA --root /tmp --parent ca mail.mycoolsite.com +``` + +### Options + +``` + --common-name string Common name for the certificate. If empty, uses the name. + -h, --help help for CreateIntermediateCA + --parent string Parent cert name to use. Use 'ca' for the toplevel CA. (default "ca") + --serial string Serial number for the certificate to create. Should be different for two certificates with the same parent. (default "01") +``` + +### Options inherited from parent commands + +``` + --root string root directory for all artifacts (default ".") +``` + +### SEE ALSO + +* [vttlstest](../) - vttlstest is a tool for generating test certificates, keys, and related artifacts for TLS tests. + diff --git a/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateSignedCert.md b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateSignedCert.md new file mode 100644 index 000000000..cee912e0a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_CreateSignedCert.md @@ -0,0 +1,42 @@ +--- +title: CreateSignedCert +series: vttlstest +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vttlstest CreateSignedCert + +Create signed certificate + +### Synopsis + +Create signed certificate + +``` +vttlstest CreateSignedCert [--root ] [--parent ] [--serial ] [--common-name ] +``` + +### Examples + +``` +CreateSignedCert --root /tmp --common-name mail.mysite.com --parent mail.mycoolsite.com postman1 +``` + +### Options + +``` + --common-name string Common name for the certificate. If empty, uses the name. + -h, --help help for CreateSignedCert + --parent string Parent cert name to use. Use 'ca' for the toplevel CA. (default "ca") + --serial string Serial number for the certificate to create. Should be different for two certificates with the same parent. (default "01") +``` + +### Options inherited from parent commands + +``` + --root string root directory for all artifacts (default ".") +``` + +### SEE ALSO + +* [vttlstest](../) - vttlstest is a tool for generating test certificates, keys, and related artifacts for TLS tests. + diff --git a/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_RevokeCert.md b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_RevokeCert.md new file mode 100644 index 000000000..e2de9ef4c --- /dev/null +++ b/content/en/docs/19.0/reference/programs/vttlstest/vttlstest_RevokeCert.md @@ -0,0 +1,40 @@ +--- +title: RevokeCert +series: vttlstest +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## vttlstest RevokeCert + +Revoke a certificate + +### Synopsis + +Revoke a certificate + +``` +vttlstest RevokeCert [--root ] [--parent ] +``` + +### Examples + +``` +RevokeCert --root /tmp --parent mail.mycoolsite.com postman1 +``` + +### Options + +``` + -h, --help help for RevokeCert + --parent string Parent cert name to use. Use 'ca' for the toplevel CA. (default "ca") +``` + +### Options inherited from parent commands + +``` + --root string root directory for all artifacts (default ".") +``` + +### SEE ALSO + +* [vttlstest](../) - vttlstest is a tool for generating test certificates, keys, and related artifacts for TLS tests. + diff --git a/content/en/docs/19.0/reference/programs/zk/_index.md b/content/en/docs/19.0/reference/programs/zk/_index.md new file mode 100644 index 000000000..a43fec56e --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/_index.md @@ -0,0 +1,50 @@ +--- +title: zk +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk + +zk is a tool for wrangling zookeeper. + +### Synopsis + +zk is a tool for wrangling zookeeper. + +It tries to mimic unix file system commands wherever possible, but +there are some slight differences in flag handling. + +The zk tool looks for the address of the cluster in /etc/zookeeper/zk_client.conf, +or the file specified in the ZK_CLIENT_CONFIG environment variable. + +The local cell may be overridden with the ZK_CLIENT_LOCAL_CELL environment +variable. + +### Options + +``` + -h, --help help for zk + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --security_policy string the name of a registered security policy to use for controlling access to URLs - empty means allow all for anyone (built-in policies: deny-all, read-only) + --server string server(s) to connect to +``` + +### SEE ALSO + +* [zk addAuth](./zk_addauth/) - +* [zk cat](./zk_cat/) - +* [zk chmod](./zk_chmod/) - +* [zk cp](./zk_cp/) - +* [zk edit](./zk_edit/) - Create a local copy, edit, and write changes back to cell. +* [zk ls](./zk_ls/) - +* [zk rm](./zk_rm/) - +* [zk stat](./zk_stat/) - +* [zk touch](./zk_touch/) - Change node access time. +* [zk unzip](./zk_unzip/) - +* [zk wait](./zk_wait/) - Sets a watch on the node and then waits for an event to fire. +* [zk watch](./zk_watch/) - Watches for changes to nodes and prints events as they occur. +* [zk zip](./zk_zip/) - Store a zk tree in a zip archive. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_addAuth.md b/content/en/docs/19.0/reference/programs/zk/zk_addAuth.md new file mode 100644 index 000000000..5d7851548 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_addAuth.md @@ -0,0 +1,23 @@ +--- +title: addAuth +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk addAuth + + + +``` +zk addAuth [flags] +``` + +### Options + +``` + -h, --help help for addAuth +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_cat.md b/content/en/docs/19.0/reference/programs/zk/zk_cat.md new file mode 100644 index 000000000..023d49e20 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_cat.md @@ -0,0 +1,35 @@ +--- +title: cat +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk cat + + + +``` +zk cat [ ...] [flags] +``` + +### Examples + +``` +zk cat /zk/path + +# List filename before file data +zk cat -l /zk/path1 /zk/path2 +``` + +### Options + +``` + -p, --decodeProto decode proto files and display them as text + -f, --force no warning on nonexistent node + -h, --help help for cat + -l, --longListing long listing +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_chmod.md b/content/en/docs/19.0/reference/programs/zk/zk_chmod.md new file mode 100644 index 000000000..ef9680e35 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_chmod.md @@ -0,0 +1,30 @@ +--- +title: chmod +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk chmod + + + +``` +zk chmod [flags] +``` + +### Examples + +``` +zk chmod n-mode /zk/path +zk chmod n+mode /zk/path +``` + +### Options + +``` + -h, --help help for chmod +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_cp.md b/content/en/docs/19.0/reference/programs/zk/zk_cp.md new file mode 100644 index 000000000..c4dee8147 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_cp.md @@ -0,0 +1,33 @@ +--- +title: cp +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk cp + + + +``` +zk cp [flags] +``` + +### Examples + +``` +zk cp /zk/path . +zk cp ./config /zk/path/config + +# Trailing slash indicates directory +zk cp ./config /zk/path/ +``` + +### Options + +``` + -h, --help help for cp +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_edit.md b/content/en/docs/19.0/reference/programs/zk/zk_edit.md new file mode 100644 index 000000000..5c0d0eb97 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_edit.md @@ -0,0 +1,24 @@ +--- +title: edit +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk edit + +Create a local copy, edit, and write changes back to cell. + +``` +zk edit [flags] +``` + +### Options + +``` + -f, --force no warning on nonexistent node + -h, --help help for edit +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_ls.md b/content/en/docs/19.0/reference/programs/zk/zk_ls.md new file mode 100644 index 000000000..4a7bf879a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_ls.md @@ -0,0 +1,40 @@ +--- +title: ls +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk ls + + + +``` +zk ls [flags] +``` + +### Examples + +``` +zk ls /zk +zk ls -l /zk + +# List directory node itself) +zk ls -ld /zk + +# Recursive (expensive) +zk ls -R /zk +``` + +### Options + +``` + -d, --directorylisting list directory instead of contents + -f, --force no warning on nonexistent node + -h, --help help for ls + -l, --longlisting long listing + -R, --recursivelisting recursive listing +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_rm.md b/content/en/docs/19.0/reference/programs/zk/zk_rm.md new file mode 100644 index 000000000..384e70bc3 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_rm.md @@ -0,0 +1,37 @@ +--- +title: rm +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk rm + + + +``` +zk rm [flags] +``` + +### Examples + +``` +zk rm /zk/path + +# Recursive. +zk rm -R /zk/path + +# No error on nonexistent node. +zk rm -f /zk/path +``` + +### Options + +``` + -f, --force no warning on nonexistent node + -h, --help help for rm + -r, --recursivedelete recursive delete +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_stat.md b/content/en/docs/19.0/reference/programs/zk/zk_stat.md new file mode 100644 index 000000000..eb50f9a05 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_stat.md @@ -0,0 +1,24 @@ +--- +title: stat +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk stat + + + +``` +zk stat [flags] +``` + +### Options + +``` + -f, --force no warning on nonexistent node + -h, --help help for stat +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_touch.md b/content/en/docs/19.0/reference/programs/zk/zk_touch.md new file mode 100644 index 000000000..298cb2826 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_touch.md @@ -0,0 +1,44 @@ +--- +title: touch +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk touch + +Change node access time. + +### Synopsis + +Change node access time. + +NOTE: There is no mkdir - just touch a node. +The disntinction between file and directory is not relevant in zookeeper. + +``` +zk touch [flags] +``` + +### Examples + +``` +zk touch /zk/path + +# Don't create, just touch timestamp. +zk touch -c /zk/path + +# Create all parts necessary (think mkdir -p). +zk touch -p /zk/path +``` + +### Options + +``` + -p, --createparent create parents + -h, --help help for touch + -c, --touchonly touch only - don't create +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_unzip.md b/content/en/docs/19.0/reference/programs/zk/zk_unzip.md new file mode 100644 index 000000000..73d653111 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_unzip.md @@ -0,0 +1,30 @@ +--- +title: unzip +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk unzip + + + +``` +zk unzip [flags] +``` + +### Examples + +``` +zk unzip zktree.zip / +zk unzip zktree.zip /zk/prefix +``` + +### Options + +``` + -h, --help help for unzip +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_wait.md b/content/en/docs/19.0/reference/programs/zk/zk_wait.md new file mode 100644 index 000000000..217a88e47 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_wait.md @@ -0,0 +1,34 @@ +--- +title: wait +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk wait + +Sets a watch on the node and then waits for an event to fire. + +``` +zk wait [flags] +``` + +### Examples + +``` + # Wait for node change or creation. +zk wait /zk/path + +# Trailing slash waits on children. +zk wait /zk/path/children/ +``` + +### Options + +``` + -e, --exit exit if the path already exists + -h, --help help for wait +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_watch.md b/content/en/docs/19.0/reference/programs/zk/zk_watch.md new file mode 100644 index 000000000..961a85226 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_watch.md @@ -0,0 +1,29 @@ +--- +title: watch +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk watch + +Watches for changes to nodes and prints events as they occur. + +``` +zk watch [flags] +``` + +### Examples + +``` +watch /zk/path +``` + +### Options + +``` + -h, --help help for watch +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zk/zk_zip.md b/content/en/docs/19.0/reference/programs/zk/zk_zip.md new file mode 100644 index 000000000..c4956dc64 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zk/zk_zip.md @@ -0,0 +1,30 @@ +--- +title: zip +series: zk +commit: 0e61ba498e0344d37d6e1cae933ae14aa2804fcd +--- +## zk zip + +Store a zk tree in a zip archive. + +### Synopsis + +Store a zk tree in a zip archive. + +Note this won't be immediately useful to the local filesystem since znodes can have data and children; +that is, even "directories" can contain data. + +``` +zk zip [ ...] [flags] +``` + +### Options + +``` + -h, --help help for zip +``` + +### SEE ALSO + +* [zk](../) - zk is a tool for wrangling zookeeper. + diff --git a/content/en/docs/19.0/reference/programs/zkctl/_index.md b/content/en/docs/19.0/reference/programs/zkctl/_index.md new file mode 100644 index 000000000..f748c565a --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zkctl/_index.md @@ -0,0 +1,45 @@ +--- +title: zkctl +series: zkctl +commit: 30385807689b40668d60dbb5059ea0987f19da5c +--- +## zkctl + +Initializes and controls zookeeper with Vitess-specific configuration. + +### Options + +``` + --alsologtostderr log to standard error as well as files + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [$WORKDIR]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + -h, --help help for zkctl + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --zk.cfg string zkid@server1:leaderPort1:electionPort1:clientPort1,...) (default "6@:3801:3802:3803") + --zk.extra stringArray extra config line(s) to append verbatim to config (flag can be specified more than once) + --zk.myid uint which server do you want to be? only needed when running multiple instance on one box, otherwise myid is implied by hostname +``` + +### SEE ALSO + +* [zkctl init](./zkctl_init/) - Generates a new config and then starts zookeeper. +* [zkctl shutdown](./zkctl_shutdown/) - Terminates a zookeeper server but keeps its data dir intact. +* [zkctl start](./zkctl_start/) - Runs an already initialized zookeeper server. +* [zkctl teardown](./zkctl_teardown/) - Shuts down the zookeeper server and removes its data dir. + diff --git a/content/en/docs/19.0/reference/programs/zkctl/zkctl_init.md b/content/en/docs/19.0/reference/programs/zkctl/zkctl_init.md new file mode 100644 index 000000000..047a07b33 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zkctl/zkctl_init.md @@ -0,0 +1,51 @@ +--- +title: init +series: zkctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## zkctl init + +Generates a new config and then starts zookeeper. + +``` +zkctl init [flags] +``` + +### Options + +``` + -h, --help help for init +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --zk.cfg string zkid@server1:leaderPort1:electionPort1:clientPort1,...) (default "6@:3801:3802:3803") + --zk.extra stringArray extra config line(s) to append verbatim to config (flag can be specified more than once) + --zk.myid uint which server do you want to be? only needed when running multiple instance on one box, otherwise myid is implied by hostname +``` + +### SEE ALSO + +* [zkctl](../) - Initializes and controls zookeeper with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/zkctl/zkctl_shutdown.md b/content/en/docs/19.0/reference/programs/zkctl/zkctl_shutdown.md new file mode 100644 index 000000000..8e81da765 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zkctl/zkctl_shutdown.md @@ -0,0 +1,51 @@ +--- +title: shutdown +series: zkctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## zkctl shutdown + +Terminates a zookeeper server but keeps its data dir intact. + +``` +zkctl shutdown [flags] +``` + +### Options + +``` + -h, --help help for shutdown +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --zk.cfg string zkid@server1:leaderPort1:electionPort1:clientPort1,...) (default "6@:3801:3802:3803") + --zk.extra stringArray extra config line(s) to append verbatim to config (flag can be specified more than once) + --zk.myid uint which server do you want to be? only needed when running multiple instance on one box, otherwise myid is implied by hostname +``` + +### SEE ALSO + +* [zkctl](../) - Initializes and controls zookeeper with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/zkctl/zkctl_start.md b/content/en/docs/19.0/reference/programs/zkctl/zkctl_start.md new file mode 100644 index 000000000..69c785b38 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zkctl/zkctl_start.md @@ -0,0 +1,51 @@ +--- +title: start +series: zkctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## zkctl start + +Runs an already initialized zookeeper server. + +``` +zkctl start [flags] +``` + +### Options + +``` + -h, --help help for start +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --zk.cfg string zkid@server1:leaderPort1:electionPort1:clientPort1,...) (default "6@:3801:3802:3803") + --zk.extra stringArray extra config line(s) to append verbatim to config (flag can be specified more than once) + --zk.myid uint which server do you want to be? only needed when running multiple instance on one box, otherwise myid is implied by hostname +``` + +### SEE ALSO + +* [zkctl](../) - Initializes and controls zookeeper with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/zkctl/zkctl_teardown.md b/content/en/docs/19.0/reference/programs/zkctl/zkctl_teardown.md new file mode 100644 index 000000000..bd44e42a9 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zkctl/zkctl_teardown.md @@ -0,0 +1,51 @@ +--- +title: teardown +series: zkctl +commit: b089f78945653f6acd17c66f896820e36df49437 +--- +## zkctl teardown + +Shuts down the zookeeper server and removes its data dir. + +``` +zkctl teardown [flags] +``` + +### Options + +``` + -h, --help help for teardown +``` + +### Options inherited from parent commands + +``` + --alsologtostderr log to standard error as well as files + --config-file string Full path of the config file (with extension) to use. If set, --config-path, --config-type, and --config-name are ignored. + --config-file-not-found-handling ConfigFileNotFoundHandling Behavior when a config file is not found. (Options: error, exit, ignore, warn) (default warn) + --config-name string Name of the config file (without extension) to search for. (default "vtconfig") + --config-path strings Paths to search for config files in. (default [/Users/andrew/dev/vtwebsite/vitessio.website/vitess]) + --config-persistence-min-interval duration minimum interval between persisting dynamic config changes back to disk (if no change has occurred, nothing is done). (default 1s) + --config-type string Config file type (omit to infer config type from file extension). + --keep_logs duration keep logs for this long (using ctime) (zero to keep forever) + --keep_logs_by_mtime duration keep logs for this long (using mtime) (zero to keep forever) + --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) + --log_dir string If non-empty, write log files in this directory + --log_err_stacks log stack traces for errors + --log_rotate_max_size uint size in bytes at which logs are rotated (glog.MaxSize) (default 1887436800) + --logtostderr log to standard error instead of files + --pprof strings enable profiling + --purge_logs_interval duration how often try to remove old logs (default 1h0m0s) + --stderrthreshold severity logs at or above this threshold go to stderr (default 1) + --v Level log level for V logs + -v, --version print binary version + --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging + --zk.cfg string zkid@server1:leaderPort1:electionPort1:clientPort1,...) (default "6@:3801:3802:3803") + --zk.extra stringArray extra config line(s) to append verbatim to config (flag can be specified more than once) + --zk.myid uint which server do you want to be? only needed when running multiple instance on one box, otherwise myid is implied by hostname +``` + +### SEE ALSO + +* [zkctl](../) - Initializes and controls zookeeper with Vitess-specific configuration. + diff --git a/content/en/docs/19.0/reference/programs/zkctld/_index.md b/content/en/docs/19.0/reference/programs/zkctld/_index.md new file mode 100644 index 000000000..a5d600cf4 --- /dev/null +++ b/content/en/docs/19.0/reference/programs/zkctld/_index.md @@ -0,0 +1,19 @@ +--- +title: zkctld +series: zkctld +commit: b2d7604e4e0728329314500c182c3192cee74510 +--- +## zkctld + +zkctld is a daemon that starts or initializes ZooKeeper with Vitess-specific configuration. It will stay running as long as the underlying ZooKeeper server, and will pass along SIGTERM. + +``` +zkctld [flags] +``` + +### Options + +``` + -h, --help help for zkctld +``` + diff --git a/content/en/docs/19.0/reference/query-serving/_index.md b/content/en/docs/19.0/reference/query-serving/_index.md new file mode 100644 index 000000000..d53f66916 --- /dev/null +++ b/content/en/docs/19.0/reference/query-serving/_index.md @@ -0,0 +1,5 @@ +--- +title: Query Serving +description: Query Serving related reference docs +weight: 2 +--- diff --git a/content/en/docs/19.0/reference/query-serving/reserved-conn.md b/content/en/docs/19.0/reference/query-serving/reserved-conn.md new file mode 100644 index 000000000..bf5644a8e --- /dev/null +++ b/content/en/docs/19.0/reference/query-serving/reserved-conn.md @@ -0,0 +1,148 @@ +--- +title: Reserved Connections +description: +weight: 1 +--- + +## Feature Description + +Vitess uses connection pooling to minimize memory usage and otherwise +optimize the performance of the underlying MySQL servers. Even with +tens of thousands of client database connections. This means that +different users connecting to a `vtgate` can effectively share a +database session to MySQL. To make this process as transparent as possible +to users, Vitess removes all query constructs that would normally +need to change the state in the MySQL connection. For example, when a user +sets or evaluates a user defined variable, the `vtgate` will rewrite the query +so that it does not actually do anything with user variables. Instead, it keeps +the state in the Vitess layer. + +In other cases, this approach is not enough, and Vitess can use +**reserved connections**, which are controlled via the `--enable_system_settings` vtgate flag. +Enabling reserved connections means a dedicated connection is maintained for +the `vtgate` session from the relevant `vttablet` to the MySQL server. Reserved +connections are used when changing system variables, using temporary tables, +or when using MySQL locking functions to acquire advisory locks. In general, it +is better to use reserved connections sparingly, because they reduce the +effectiveness of the `vttablet` connection pooling. This may also reduce, or even +eliminate, the advantages of using connection pooling between `vttablet` and +MySQL. As such, take note of the `SET` statements that your application's +MySQL connector and/or ORM sends to MySQL/`vtgate`. Or if those settings will +result in reserved connections being employed for some/all of the application's +sessions. + +### Settings pool and reserved connections + +We will see how reserved connections get triggered for different use cases in subsequent sections of this document. +What we want to highlight at the beginning is that there is a known issue when a reserved connection is used as it cannot be reused by vttablet. More details about it are given [below](#number-of-vttablet---mysql-connections). + +To solve this problem, the connection pool implementation used by vttablet has been enhanced to keep the connections with settings in the pool and not to pin the connection to the client session. +With this enhancement, we reduce the likelihood of MySQL running out of connections due to reserved connections, because the scenarios where we still need reserved connections are sharply reduced. + +This is enabled by default from v17 onwards. It can be disabled by setting the flag `--queryserver-enable-settings-pool` on vttablet. +This change takes effect only for the cases when system variable changes need a reserved connection. +There are still cases like [temporary tables](#temporary-tables-and-reserved-connections) and [advisory locks](#get_lock-and-reserved-connections) where reserved connections will continue to be used. + +### System variables and reserved connections + +If a user changes a system variable and reserved connections are enabled, +the user connection will be marked as needing reserved connections. +For all subsequent calls to Vitess, connection pooling is turned off for +a particular session. This only applies to certain system settings. For more +details see [here](../../../../design-docs/query-serving/set-stmt/). Any queries to a +tablet from this session will create a reserved connection on that tablet. This +means a connection is reserved only for that session. + +Connection pooling is an important part of what makes Vitess performant, so +using constructs that turn it off should only be done in rare circumstances. + +If you are using an application or library that issues these kind of `SET` +statements, the best way to avoid reserved connections is to make sure the +global MySQL settings match the ones the application is trying to set (e.g. +`sql_mode`, or `wait_timeout`). When Vitess discovers that you are changing +a system setting to the global value, Vitess just ignores those `SET`s. + +Once a session has been marked as reserved, it remain reserved until the user +disconnects from `vtgate`. + +### Enabling reserved connections + +Use of reserved connections are controlled by the `vtgate` flag +`--enable_system_settings`. This flag has traditionally defaulted to **false** +(or off) in release versions (i.e. `x.0` and `x.0.y`) of Vitess, and to +**true** (or on) in development versions. + +From Vitess 12.0 onwards, it defaults to **true** in all release and +development versions. You can read more [here](https://github.com/vitessio/vitess/issues/9125). +Thus you should specify this flag explicitly, so you are sure whether +it is enabled or not, independent of which Vitess release/build/version +you are running. + +If you have reserved connections disabled, you will get the "old" Vitess behavior: +where most setting most system settings (e.g. `sql_mode`) are just silently +ignored by Vitess. In situations where you know your backend MySQL defaults +are acceptable, this may be the correct tradeoff to ensure the best possible +performance of the `vttablet` <-> MySQL connection pools. As noted above, +this comes down to a trade-off between compatibility and +performance/scalability. You should also review [this section](#number-of-vttablet---mysql-connections) +when deciding on whether or not to enable reserved connections. + +### Avoiding the use of reserved connections + +In MySQL80 a new query hint (`SET_VAR`) allows setting the session value of certain system variables during +the execution of a statement. More information about this MySQL feature on the +[MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html#optimizer-hints-set-var). +Vitess leverages this query hint to reduce the number of reserved connections. When setting a system variable, +instead of creating a reserved connection, the variable and its new value will be sent to MySQL using the +`SET_VAR` query hint. This applies only if the system variable is supported by the `SET_VAR` hint +(list of supported variables [here](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html)). + + +For example, executing: `set @@sql_mode = 'NO_ZERO_DATE'` will not create a reserved connection for future queries. +If we execute a `select` statement like: `select foo from bar`, VTGate will rewrite the query as +`select /*+ SET_VAR(sql_mode = 'NO_ZERO_DATE') foo from bar */`. + +This feature can be disabled using the VTGate flag `--enable_set_var` (by default set to true). + +### Temporary tables and reserved connections + +Temporary tables exist only in the context of a particular MySQL connection. +If using a temporary table, Vitess will mark the session as needing a +reserved connection. It will continue to use the reserved connection +until the user disconnects. Note that removing the temp table is not enough to reset this. +More info can be found [here](../../compatibility/mysql-compatibility/#temporary-tables). + +### GET_LOCK() and reserved connections + +The MySQL locking functions allow users to work with user level locks. Since +the locks are tied to the connection, and the lock must be released in the +same connection as it was acquired, use of these functions will force a +connection to become a reserved connection. This connection is also kept alive +so it does not time out due to inactivity. More information can be found +[here](../../../../design-docs/query-serving/locking-functions/). + +### Shutting down reserved connections + +Whenever a connection gets transformed into a reserved connection, a fresh +connection is created in the connection pool to replace it. Once the `vtgate` +session that initiated the reserved connections disconnects, all reserved +connections created for this session between the `vttablet`s and MySQL +are terminated. You may want to configure your application or application +connector to disconnect idle sessions that are likely to use +reserved connections promptly. In order to release resources that cannot +otherwise be reused. + +### Number of vttablet <-> MySQL connections + +As a result of how reserved connections work, it is possible for there +to be significantly more `vttablet` <-> MySQL connections than the limit you +set by sizing the `vttablet` connection pools. This is because the connection +pools are still being maintained. Which results in a set maximum number of +connections, plus the number of reserved connections. This is at +least partially based on the number of connected vtgate clients that are using +reserved connections. As such, it may be challenging to size your MySQL +`max_connections` configuration setting appropriately in order to deal with the +potentially (much) larger number of connections. + +We recommend you review the value of this setting carefully, and keep this +in mind when you decide whether to enable or disable reserved connections. diff --git a/content/en/docs/19.0/reference/viper/_index.md b/content/en/docs/19.0/reference/viper/_index.md new file mode 100644 index 000000000..60335c193 --- /dev/null +++ b/content/en/docs/19.0/reference/viper/_index.md @@ -0,0 +1,3 @@ +--- +title: Viper +--- \ No newline at end of file diff --git a/content/en/docs/19.0/reference/viper/basic.md b/content/en/docs/19.0/reference/viper/basic.md new file mode 100644 index 000000000..a2ba89547 --- /dev/null +++ b/content/en/docs/19.0/reference/viper/basic.md @@ -0,0 +1,70 @@ +--- +title: Framework Basics +weight: 2 +--- + +In order to integrate smoothly with existing Vitess configuration mechanisms (including flags, `vttablet`'s YAML-based configuration, `/debug/env` endpoints, etc) we have introduced a thin framework on top of viper, which: + +- Requires values to be `Configure`d. +- Separates static values (which do not change at runtime even if the config-file they were loaded from is updated) from dynamic values. + +## `Configure` Options + +In order to properly configure a value for use, `Configure` needs to know, broadly speaking, three things: + +1. The key name being bound. +1. What "things" it should be bound to (i.e. other keys via aliases, environment variables, and flag names), as well as if it has a default value. +1. How to `Get` it out of a viper. + +`Configure`, therefore, has the following signature: + +```go +func Configure[T any](key string, options Options[T]) Value[T] +``` + +The first parameter provides the key name (point 1 of our above list); all other information is provided via various `Options` fields, which looks like: + +```go +type Options[T any] struct { + // what "things" to bind to + Aliases []string + FlagName string + EnvVars []string + + // default, if any + Default T + + // whether it can reload or not (more on this later) + Dynamic bool + + // how to "get" it from a viper (more on this slightly less later) + GetFunc func(v *viper.Viper) func(key string) T +} +``` + +## `Get` funcs + +In most cases, module authors will not need to specify a `GetFunc` option, since, if not provided, `viperutil` will do its best to provide a sensible default for the given type `T`. + +This requires a fair amount of `reflect`ion code, which we won't go into here, and unfortunately cannot support even all primitive types (notably, array (not slice!!) types). +In these cases, the `GetFuncForType` will panic, allowing the module author to catch this during testing of their package. +They may then provide their own `GetFunc`. + +The full suite of types, both supported and panic-inducing, are documented by way of unit tests in [`go/viperutil/get_func_test.go`](https://github.com/vitessio/vitess/blob/main/go/viperutil/get_func_test.go). + +## Debug Endpoint + +Any component that parses its flags via one of `servenv`'s parsing methods will get an HTTP endpoint registered at `/debug/config` which displays the full viper configuration for debugging purposes. +It accepts a query parameter to control the format; anything in `viper.SupportedExts` is permitted. + +## Caveats and Gotchas + +- Config keys are case-insensitive. +`Foo`, `foo`, `fOo`, and `FOO` will all have the same value. + - **Except** for environment variables, which, when read, are case-sensitive (but the config key they are _bound to_ remains case-insensitive). + For example, if you have `viper.BindEnv("foo", "VT_FOO")`, then `VT_FOO=1 ./myprogram` will set the value to `1`, but `Vt_FoO=1 ./myprogram will not`. + The value, though, can still be read _from_ viper as `Foo`, `foo`, `FOO`, and so on. + +- The `Unmarshal*` functions rely on `mapstructure` tags, not `json|yaml|...` tags. + +- Any config files/paths added _after_ calling `WatchConfig` will not get picked up by that viper, and a viper can only watch a single config file. \ No newline at end of file diff --git a/content/en/docs/19.0/reference/viper/config_files.md b/content/en/docs/19.0/reference/viper/config_files.md new file mode 100644 index 000000000..753ba3206 --- /dev/null +++ b/content/en/docs/19.0/reference/viper/config_files.md @@ -0,0 +1,69 @@ +--- +title: Config Files +weight: 4 +slug: 'config-files' +--- + +`viperutil` provides a few flags that allow binaries to read values from config files in addition to defaults, environment variables and flags. +They are: + +- `--config-path` + - Default: `$(pwd)` + - EnvVar: `VT_CONFIG_PATH` (parsed exactly like a `$PATH` style shell variable). + - FlagType: `StringSlice` + - Behavior: Paths for `ReadInConfig` to search. +- `--config-type` + - Default: `""` + - EnvVar: `VT_CONFIG_TYPE` + - FlagType: `flagutil.StringEnum` + - Values: everything contained in `viper.SupportedExts`, case-insensitive. + - Behavior: Force viper to use a particular unmarshalling strategy; required if the config file does not have an extension (by default, viper infers the config type from the file extension). +- `--config-name` + - Default: `"vtconfig"` + - EnvVar: `VT_CONFIG_NAME` + - FlagType: `string` + - Behavior: Instructs `ReadInConfig` to only look in `ConfigPaths` for files named with this name (with any supported extension, unless `ConfigType` is also set, in which case only with that extension). +- `--config-file` + - Default: `""` + - EnvVar: `VT_CONFIG_FILE` + - FlagType: `string` + - Behavior: Instructs `ReadInConfig` to search in `ConfigPaths` for explicitly a file with this name. Takes precedence over `ConfigName`. +- `--config-file-not-found-handling` + - Default: `WarnOnConfigFileNotFound` + - EnvVar: (none) + - FlagType: `string` (options: `IgnoreConfigFileNotFound`, `WarnOnConfigFileNotFound`, `ErrorOnConfigFileNotFound`, `ExitOnConfigFileNotFound`) + - Behavior: If viper is unable to locate a config file (based on the other flags here), then `LoadConfig` will: + - `Ignore` => do nothing, return no error. Program values will come entirely from defaults, environment variables and flags. + - `Warn` => log at the WARNING level, but return no error. + - `Error` => log at the ERROR level and return the error back to the caller (usually `servenv`.) + - `Exit` => log at the FATAL level, exiting immediately. +- `--config-persistence-min-interval` + - Default: `1s` + - EnvVar: `VT_CONFIG_PERSISTENCE_MIN_INTERVAL` + - FlagType: `time.Duration` + - Behavior: If viper is watching a config file, in order to synchronize between changes to the file, and changes made in-memory to dynamic values (for example, via vtgate's `/debug/env` endpoint), it will periodically write in-memory changes back to disk, waiting _at least_ this long between writes. + If the value is 0, each in-memory `Set` is immediately followed by a write to disk. + +For more information on how viper searches for config files, see the [documentation][viper_read_in_config_docs]. + +If viper was able to locate and load a config file, `LoadConfig` will then configure the dynamic registry to set up a watch on that file, enabling all dynamic values to pick up changes to that file for the remainder of the program's execution. +If no config file was used, then dynamic values behave exactly like static values (i.e. the dynamic registry copies in the settings loaded into the static registry, but does not set up a file watch). + +## Re-persistence for Dynamic Values + +Prior to the introduction of viper in Vitess, certain components (such as `vttablet` or `vtgate`) exposed `/debug/env` HTTP endpoints that permitted the user to modify certain configuration parameters at runtime. + +This behavior is still supported, and to maintain consistency between update mechanisms, if: +- A config file was loaded at startup +- A value is configured with the `Dynamic: true` option + +then in-memory updates to that value (via `.Set()`) will be written back to disk. +If we skipped this step, then the next time viper reloaded the disk config, the in-memory change would be undone, since viper does a full load rather than something more differential. +Unfortunately, this seems unavoidable. + +To migitate against potentially writing to disk "too often" for a given user, the `--config-persistence-min-interval` flag defines the _minimum_ time to wait between writes. +Internally, the system is notified to write "soon" only when a dynamic value is updated. +If the wait period has elapsed between changes, a write happens immediately; otherwise, the system waits out the remainder of the period and persists any changes that happened while it was waiting. +Setting this interval to zero means that writes happen immediately. + +[viper_read_in_config_docs]: https://github.com/spf13/viper#reading-config-files diff --git a/content/en/docs/19.0/reference/viper/dynamic_values.md b/content/en/docs/19.0/reference/viper/dynamic_values.md new file mode 100644 index 000000000..a9d3d47fb --- /dev/null +++ b/content/en/docs/19.0/reference/viper/dynamic_values.md @@ -0,0 +1,17 @@ +--- +title: Dynamic Values +weight: 3 +slug: 'dynamic-values' +--- + +Values can be configured to be either static or dynamic. +Static values are loaded once at startup (more precisely, when `viperutil.LoadConfig` is called), and whatever value is loaded at the point will be the result of calling `Get` on that value for the remainder of the process's lifetime. +Dynamic values, conversely, may respond to config changes. + +In order for dynamic configs to be truly dynamic, `LoadConfig` must have found a config file (as opposed to pulling values entirely from defaults, flags, and environment variables). +If this is the case, a second viper shim, which backs the dynamic registry, will start a watch on that file, and any changes to that file will be reflected in the `Get` methods of any values configured with `Dynamic: true`. + +**An important caveat** is that viper on its own is not threadsafe, meaning that if a config reload is being processed while a value is being accessed, a race condition can occur. +To protect against this, the dynamic registry uses a second shim, [`sync.Viper`](https://github.com/vitessio/vitess/blob/main/go/viperutil/internal/sync/sync.go). +This works by assigning each dynamic value its own `sync.RWMutex`, and locking it for writes whenever a config change is detected. Value `GetFunc`s are then adapted to wrap the underlying get in a `m.RLock(); defer m.RUnlock()` layer. +This means that there's a potential throughput impact of using dynamic values, which module authors should be aware of when deciding to make a given value dynamic. diff --git a/content/en/docs/19.0/reference/viper/overview.md b/content/en/docs/19.0/reference/viper/overview.md new file mode 100644 index 000000000..5c0c67fd2 --- /dev/null +++ b/content/en/docs/19.0/reference/viper/overview.md @@ -0,0 +1,19 @@ +--- +title: Overview +weight: 1 +--- + +Vitess v17 introduced [`viper`][viper], a library to provide unified configuration management, to the project. + +It acts as a registry for configuration values coming from a variety of sources, including: + +- Default values. +- Configuration files (JSON, YAML, TOML, and other formats supported), including optionally watching and live-reloading. +- Environment variables. +- Command-line flags, primarily from `pflag.Flag` types. + +It is used by a wide variety of Go projects, including [hugo][hugo] and [kops][kops]. + +[viper]: https://github.com/spf13/viper +[hugo]: https://github.com/gohugoio/hugo +[kops]: https://github.com/kubernetes/kops diff --git a/content/en/docs/19.0/reference/vreplication/_index.md b/content/en/docs/19.0/reference/vreplication/_index.md new file mode 100644 index 000000000..018af89d2 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/_index.md @@ -0,0 +1,7 @@ +--- +title: VReplication +description: "VReplication vtctl commands" +weight: 3 +aliases: ['/docs/reference/vreplication/v2/'] +skip_sections: true +--- diff --git a/content/en/docs/19.0/reference/vreplication/createlookupvindex.md b/content/en/docs/19.0/reference/vreplication/createlookupvindex.md new file mode 100644 index 000000000..8acf91cbd --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/createlookupvindex.md @@ -0,0 +1,48 @@ +--- +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/faq.md b/content/en/docs/19.0/reference/vreplication/faq.md new file mode 100644 index 000000000..d41262d00 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/faq.md @@ -0,0 +1,44 @@ +--- +title: VReplication FAQ +description: Common issues/questions while operating VReplication workflows. +weight: 400 +--- + +{{< expand `What mysql permissions are needed by VReplication?`>}} +
+GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, PROCESS, FILE, 
+  REFERENCES, INDEX, ALTER, SHOW DATABASES, CREATE TEMPORARY TABLES,
+  LOCK TABLES, EXECUTE, REPLICATION SLAVE, REPLICATION CLIENT, CREATE VIEW,
+  SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, CREATE USER, EVENT, TRIGGER
+  ON *.* TO 'vt_filtered'@'localhost';
+
+{{< /expand >}} + +{{< expand `Why am I seeing io.EOF errors in my workflow?`>}} +

+ io.EOF errors can be difficult to track down. These are usually caused by an issue at the mysql server layer. You will need to consult + the source and target vttablet logs in order to know for sure in each case. Here are some possible reasons: +

+ +
    +
  • GTID is not enabled on the server. VReplication requires GTID=on + (permissible is not supported)
    • +
  • Permissions are not setup correctly for the vreplication related mysql users (in particular the `vt_filtered` user by defualt).
    • +
  • Row-based replication (RBR) binlog_format=row is not enabled. Statement-based replication (SBR) is not supported by VReplication
    • +
  • The mysql server is down or not reachable
    • +
+{{< /expand >}} + +{{< expand `What GTID-related options do I need to set in my my.cnf?`>}} +
+log_bin=1
+binlog_format=ROW
+binlog_row_image=full
+
+{{< /expand >}} + +{{< expand `If I can't turn GTIDs on, can I run a VReplication workflow using --db_flavor=FilePos instead?`>}} +Yes, you can run VReplication workflows with the pre MySQL 5.6 file and position method but this should only be used as a last resort when it's not possible +to modify the configuration of the source. This is because the File and Position method is not fault tolerant and if any error or failure/failover is encountered +you will need to throw away the existing workflow and start another one anew. +{{< /expand >}} diff --git a/content/en/docs/19.0/reference/vreplication/flags.md b/content/en/docs/19.0/reference/vreplication/flags.md new file mode 100644 index 000000000..23fe99e58 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/flags.md @@ -0,0 +1,198 @@ +--- +title: VTTablet Flags +description: vttablet flags related to VReplication functionality +weight: 80 +--- + +There are several flags that can be specified when `vttablet` is launched that are related to the +VReplication functionality. Some of the flags are relevant when tablets are acting as targets and others when tablets are acting as sources in a VReplication workflow. + +#### relay_log_max_size + +**Type** integer\ +**Unit** bytes\ +**Default** 250000\ +**Applicable on** target + +The target tablet receives events from the source and applies the corresponding DML to the underlying MySQL database. Depending on the load on the target the query execution times can change. Also during the copy +phase, we are doing bulk inserts. For both of these reasons VReplication introduces a buffer between receiving the events and applying them: the _relay log_. + +The relay log buffers events on the target as they are received from the source. This is done in a separate thread concurrently with the thread that applies the events. + +**relay_log_max_size** defines the maximum buffer size (in bytes). As events arrive they are stored in the relay log. The apply thread consumes these events as fast as it can. When the relay log fills up we no longer pull +events from the source until some events are consumed. If single rows are larger than the specified buffer size, a single row is buffered at a time. + +#### vreplication-parallel-insert-workers + +**Type** integer\ +**Default** 1\ +**Applicable on** target + +This flag is intended as an option to improve the performance of the [VReplication copy phase](https://vitess.io/docs/design-docs/vreplication/life-of-a-stream/#copy). + +During the VReplication copy phase, the target tablet reads batches of rows in VStream packets (the size of which is managed by the [`--vstream_packet_size` flag](#vstream_packet_size)) from the source tablet and inserts them on the target. By default, the target does this sequentially: it reads a batch, then it inserts a batch, then it reads a batch, etc. This flag adds a degree of parallelism so that, while a new batch is being read from the source, up to `--vreplication-parallel-insert-workers` may be inserting previously read batches. + +{{< info >}} +Batches of rows insert in parallel, but commit in order. In other words, given two batches B1 and B2 with all primary key IDs in B1 less than those in B2, rows in B2 may be inserted before those in B1, but the B1 transaction will commit before the B2 transaction. + +Though this limits performance, it ensures the target will be eventually consistent. +{{< /info >}} + +The performance of a VReplication stream is dependent on a number of factors, such as the hardware of the source and target tablets, the latency of the network between them, and utilization of those resources by the VReplication stream and concurrent workloads. Whether this flag improves performance depends on those factors and many others not mentioned here. + +A rule of thumb to follow is to see if there are idle resources (especially CPU and disk IO) on both the source and target side. If so, then increasing this flag may increase utilization of those resources, and improve copy phase performance. To measure effectiveness of the flag, compare the values of the [`VReplicationCopyRowCount` metric](../metrics/#vreplicationcopyrowcount-vreplicationcopyrowcounttotal) or [`VReplicationPhaseTimings` metric](../metrics/#vreplicationphasetimings-vreplicationphasetimingscounts-vreplicationphasetimingstotal) with and without the flag. + +It is recommended **not** to increase this flag beyond the number of vCPUs available to the target tablet. + +#### vreplication_copy_phase_duration + +**Type** duration\ +**Default** 1h (1 hour)\ +**Applicable on** target + +When copying the contents of a table we go through 1+ cycles of copying rows, catching up on changes made (binlog events) while we copied rows, and applying those changes to the rows that have been copied (copy,catchup,fastforward). This flag determines at most how long we copy rows before moving through the other stages in the cycle. These cycles will continue until all of the rows have been copied. + +* You can see metrics related to the copy phase in the following values at the `/debug/vars` vttablet endpoint: `VReplicationPhaseTimings`, `VReplicationPhaseTimingsCounts`, `VReplicationPhaseTimingsTotal`, `VReplicationCopyLoopCount`, `VReplicationCopyLoopCountTotal`, `VReplicationCopyRowCount`, `VReplicationCopyRowCountTotal`, `VStreamerPhaseTiming`, and `VStreamerErrors` + +{{< info >}} +You should not generally need to change this. But, you may want to increase this duration if the source has little to no write traffic occurring during the copy phase (to speed things along) and you may want to decrease it if the write rate is very high on the source during the copy phase (to ensure we can stay caught up with changes that are happening). +{{< /info >}} + +#### vreplication_copy_phase_max_innodb_history_list_length + +**Type** integer\ +**Default** 1000000\ +**Applicable on** source + +When copying the contents of a table we go through 1+ cycles of copy,catchup,fastforward in the copy phase. When preparing to copy a batch of rows (row streamer) we check the [InnoDB history list length](https://dev.mysql.com/doc/refman/en/innodb-purge-configuration.html) on the source MySQL instance and wait for it to become less than or equal to this value before beginning. This helps to limit the impact of VReplication operations such as `MoveTables` on the source tablet (especially important if the source is a PRIMARY). + +* You can see the current configuration value as `RowStreamerMaxInnoDBTrxHistLen` in the running process at the `/debug/vars` vttablet endpoint +* You can modify the current configuration value as `RowStreamerMaxInnoDBTrxHistLen` in the running process at the `/debug/env` vttablet endpoint +* You can see the total (global) number of waits and time spent waiting for MySQL on the source tablet as `waitForMySQL` in `RowStreamerWaits` at the `/debug/vars` vttablet endpoint +* You can see the number of waits and time spent waiting for MySQL on the source tablet by table (we do not have the workflow name on the source) as `:waitForMySQL` in `VStreamerPhaseTiming` at the `/debug/vars` vttablet endpoint + +#### vreplication_copy_phase_max_mysql_replication_lag + +**Type** integer\ +**Unit** seconds\ +**Default** 43200 (12 hours)\ +**Applicable on** source + +When copying the contents of a table we go through 1+ cycles of copy,catchup,fastforward in the copy phase. When preparing to copy a batch of rows (row streamer) we check the [Seconds_Behind_Source](https://dev.mysql.com/doc/refman/en/replication-administration-status.html) value on the source MySQL instance and wait for it to become less than or equal to this value before beginning. This helps to limit the impact of VReplication operations such as `MoveTables` on the source tablet. + +* You can see the current configuration value as `RowStreamerMaxMySQLReplLagSecs` in the running process at the `/debug/vars` vttablet endpoint +* You can modify the current configuration value as `RowStreamerMaxMySQLReplLagSecs` in the running process at the `/debug/env` vttablet endpoint +* You can see the total (global) number of waits and time spent waiting for MySQL on the source tablet as `waitForMySQL` in `RowStreamerWaits` at the `/debug/vars` vttablet endpoint +* You can see the number of waits and time spent waiting for MySQL on the source tablet by table (we do not have the workflow name on the source) as `:waitForMySQL` in `VStreamerPhaseTiming` at the `/debug/vars` vttablet endpoint + +#### vreplication_heartbeat_update_interval + +**Type** integer\ +**Unit** seconds\ +**Default** 1\ +**Maximum** 60 (one minute)\ +**Applicable on** target + +For an idle source shard, the source vstreamer sends a heartbeat. Currently, that is once per second. On receiving the heartbeat the target VReplication module updates the time_updated column of the relevant row of `_vt.vreplication`. For some setups this is a problem, for example: + +* If there are too many streams the extra write QPS or CPU load due to these updates are unacceptable +* If there are too many streams and/or a large source field (lot of participating tables) which generates unacceptable increase in the binlog size +* Even for a single stream, if the server is of a lower configuration, then the resulting increase in the QPS or binlog increase may become significant as a percentage of resources + +_vreplication_heartbeat_update_interval_ determines how often the time_updated column is updated if there is no activity on the source and the source vstream is only sending heartbeats. Use a low value if you expect a high QPS or you are monitoring this column to alert about potential outages. Keep this high if: + +* You have too many streams and the extra write QPS or CPU load due to these updates is unacceptable OR +* You have too many streams and/or a large binlogsource field (i.e., there are a lot of participating tables) which generates unacceptable increase in your binlog size + +Some internal processes (like OnlineDDL) depend on the heartbeat updates for operating properly. Hence there is an upper limit on this interval, which is 60 seconds. + +#### vstream-binlog-rotation-threshold + +**Type** integer\ +**Unit** bytes\ +**Default** 67108864 (64MiB)\ +**Applicable on** source + +When starting a vstream which executes a query based on a [GTID](https://dev.mysql.com/doc/refman/en/replication-gtids-concepts.html) snapshot/position (e.g. RowStreamers and ResultStreamers) we will attempt to rotate the binary log (binlog) file if the currently open binlog file on the source is larger than this value in order to limit the [GTID auto positioning](https://dev.mysql.com/doc/refman/en/replication-gtids-auto-positioning.html) overhead. The currently open binlog file — [which can be up to 1GiB in size by default](https://dev.mysql.com/doc/refman/en/replication-options-binary-log.html#sysvar_max_binlog_size) — will always need to be scanned *even when there is little to no replication lag* and empty events will be streamed for those GTIDs in the log that we are skipping. In total, this can add significant overhead on both the `mysqld` instance and the `vttablet` when starting a number of vstreams. Rotating the binlog when it's above this size helps to ensure that we are processing a relatively small open binary log file that will be minimal in both size and number of GTID events. Attempting to rotate the log if the current binlog file is of any significant size (64MiB by default) avoids too many unecessary rotations. If you're on a very fast network with low latency — and plenty of spare CPU capacity — then you may want to increase this size even further to avoid unnecessary rotations. Conversely, if you're on a very slow network with high latency then you may want to decrease this size even further to avoid longer delays when vstreams start (e.g. you may see this exhibited as a slow [`VDiff`](../vdiff) or [`MoveTables`](../movetables) operation on a number of very small tables). + +* You can see the number of successful binlog rotations that vstreams have performed (an attempt can fail e.g. due to lack of permissions) using the `VStreamerFlushedBinlogs` status variable in the running process at the [`/debug/vars` `vttablet` endpoint](../../../user-guides/configuration-basic/monitoring/#debugvars) + +#### vstream_packet_size + +**Type** integer\ +**Unit** bytes\ +**Default** 250000\ +**Applicable on** source + +On the source, events are buffered and batched where applicable, to minimize network overhead. For example, multiple row events in a transaction or the set of begin/dml/commit event sets are buffered and sent together. Commits, DDLs, and synthetic events generated by VReplication like heartbeats and resharding journals cause the events buffered on the source to be sent immediately. + +**vstream_packet_size** specifies the suggested packet size for VReplication vstreamer. This is used only as a recommendation. The actual packet size may be more or less than this amount depending on the number and type of events yet to be sent on the source. + +#### watch_replication_stream + +**Type** bool\ +**Default** false\ +**Applicable on** source + +By default vttablets reload their schema every `--queryserver-config-schema-reload-time` seconds (default 30 minutes). This can cause a problem while streaming events if DDLs are applied on the source and streaming is started _after_ the DDL was applied but _before_ vttablet refreshed its schema. This is alleviated by enabling the _watcher_. + +When enabled, vttablet will start the _watcher_ which streams the MySQL replication stream from the local database, and uses it to proactively update its schema when it encounters a DDL. + +#### track_schema_versions + +**Type** bool\ +**Default** false\ +**Applicable on** source + +All vstreams on a tablet share a common engine. vstreams that are lagging might see a newer (and hence incorrect) version of the schema in case DDLs were applied in between. Also, reloading schemas is an expensive operation. If there are multiple vstreams, each of them will separately receive a DDL event resulting in multiple reloads for the same DDL. The [tracker](../internal/tracker) addresses these issues. + +When enabled, vttablet will start the _tracker_ which runs a separate vstream that monitors DDLs and stores the version of the schema at the position that a DDL is applied in the schema version table. So if we are streaming events from the past we can get the corresponding schema and interpret the fields from the event correctly. + +#### schema-version-max-age-seconds + +**Type** integer\ +**Unit** seconds\ +**Default** 0\ +**Applicable on** source + +By default the historian loads up to 10,000 rows from the `_vt.schema_version` table into memory which contain a blob of the entire database schema. For clusters with large schemas each of these rows can become very large (>1MB) and can eventually lead to out of memory errors on the tablet if frequent DDLs are run triggering a new `_vt.schema_version` row to be written and stored in the tablet's memory. + +`schema-version-max-age-seconds` provides a way to periodically purge those schema version rows from the tablet's memory by removing rows older than the max age in seconds. The default of 0 means no records will be purged. This option **only** controls removing the records in the tablet's memory and does not remove the rows stored in the database. A safe option is to choose a max age at least as old as your [binlog retention seconds](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_expire_logs_seconds) to avoid removing schema versions that are needed to serialize binlog events that require a schema different from the most recent schema. + +#### vreplication_retry_delay + +**Type** integer\ +**Unit** seconds\ +**Default** 5\ +**Applicable on** target + +The target might encounter connection failures during a workflow. VReplication automatically retries +stalled streams after _vreplication_retry_delay_ seconds + +#### vreplication_max_time_to_retry_on_error + +**Type** duration\ +**Default** 0 (unlimited)\ +**Applicable on** target + +Stop automatically retrying when we've had consecutive failures with the same error for this long after the first occurrence (default 0, meaning no time limit). + +#### vreplication_tablet_type + +**Type** string\ +**Default** in_order:REPLICA,PRIMARY\ +**Applicable on** target + +This parameter specifies the default tablet_types that will be used by the tablet picker to find sources for a VReplication stream. It can be overridden, per workflow, by passing a different list to the workflow commands like `MoveTables` and `Reshard`. + +#### vreplication_experimental_flags + +**Type** bitmask\ +**Default** 0\ +**Applicable on** target + +Features that are not field-tested, that are not backward-compatible, or need to be proven in production environments are put behind _vreplication_experimental_flags_. These features are temporary and will either be made permanent, removed, or put behind a separate vttablet option. Currently, the only experimental features are expected to be performance improvements. + +This will be a bit-mask for each such feature. The ones currently defined: + +bitmask: *0x1* => If set then we optimize the catchup phase by not sending inserts for rows that are outside the range of primary keys already copied. More details at https://github.com/vitessio/vitess/pull/7708 diff --git a/content/en/docs/19.0/reference/vreplication/img/VReplicationFlow.png b/content/en/docs/19.0/reference/vreplication/img/VReplicationFlow.png new file mode 100644 index 000000000..9f4985563 Binary files /dev/null and b/content/en/docs/19.0/reference/vreplication/img/VReplicationFlow.png differ diff --git a/content/en/docs/19.0/reference/vreplication/img/VStream.svg b/content/en/docs/19.0/reference/vreplication/img/VStream.svg new file mode 100644 index 000000000..47b54d4a1 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/img/VStream.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/en/docs/19.0/reference/vreplication/internal/_index.md b/content/en/docs/19.0/reference/vreplication/internal/_index.md new file mode 100644 index 000000000..4f9a0179a --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/internal/_index.md @@ -0,0 +1,8 @@ +--- +title: Internals +description: Selected vreplication-related design docs and implementation details +weight: 1000 +skip_sections: true +aliases: ['/docs/reference/vreplication/internal'] +--- + diff --git a/content/en/docs/19.0/reference/vreplication/internal/cutover.md b/content/en/docs/19.0/reference/vreplication/internal/cutover.md new file mode 100644 index 000000000..6267fb56e --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/internal/cutover.md @@ -0,0 +1,308 @@ +--- +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 + +{{< info >}} +As the objects or keys noted below are stored in [the topo server](../../../features/topology-service/) and +cached locally, the processes involved will refresh their topo data throughout the cutover process. For example, each +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). +{{< /info >}} + +## VSchema + +A [VSchema](../../../../concepts/vschema/) allows you to describe how data is organized within keyspaces and shards. + +## Shard Info + +The [`global` topo](../../../features/topology-service/#global-vs-local) contains +one [`Shard`](../../../features/topology-service/#shard) key per keyspace which then contains one key per +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): + +```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 +``` + +## SrvKeyspace + +Each cell has a [`SrvKeyspace`](../../../features/topology-service/#srvkeyspace) key in +the [`local` topo](../../../features/topology-service/#global-vs-local) (per cell info) for each keyspace. For +each tablet type (e.g. `PRIMARY` or `REPLICA`) there is one `partitions` object. The `partitions` objects contain all of the +current shards in the keyspace. For sharded keyspaces, the tablets which are healthy and serving have a key range specified +for that shard. + +Also the primary can contain a `query_service_disabled` attribute which is set to `true` during resharding cutovers. +This tells the primary in that shard to reject any queries made to it, as a signal to vtgate in case vtgate routes +queries to this primary during the cutover or before it discovers the new serving graph. Here is an example using the +same unsharded commerce keyspace and here we specify the `--cell` flag so that cell's topo base path — stored in +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" + +$ 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"}} +``` + +## Routing Rules + +[Routing Rules](../../../features/schema-routing-rules) are stored in the `RoutingRules` key within +the `global` topo. Routing Rules contain a list of table-specific routes. You can route a table for all or specific +tablet types to another table in the same or different keyspace. Here is an example using the same commerce keyspace +where we have an active [`MoveTables`](../../../vreplication/movetables/) workflow to move tables to the +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"} +``` + +
+ +{{< info >}} +In practice you would instead typically view the routing rules via the +dedicated [`GetRoutingRules`](../../../programs/vtctl/schema-version-permissions/#getroutingrules) +vtctl client command which will return the rules for all keyspaces in the topo. +{{< /info >}} + +# 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')` +(a _write_ query). + +1. Check to see if `t1` has an appropriate routing rule defined. If so, use the specified target table as an alias for `t1`. +2. Locate the keyspace for `t1` using the [`VSchema`](../../../features/vschema/). +3. For a non-sharded keyspace locate the appropriate tablet (`PRIMARY`, by default) from the (cached) `SrvKeyspace` `local` +(per cell) topo record. +4. For a sharded keyspace the `SrvKeyspace` record is used to find the currently active shards. This is done by checking +the list of partitions for the specific tablet type selected for the query (`PRIMARY`, by default, for both reads and writes) +and selecting the ones whose `query_service_disabled` field is *not* set and whose `is_primary_serving` value is true. +5. Finally, based on the [`VIndex`](../../../features/vindexes/) defined for the table from the cached +[`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 + +This document outlines the steps involved in the cutover process +of [`MoveTables`](../../movetables/) and [`Reshard`](../../reshard/) +workflows when traffic is switched from the source tables/shards to the target tables/shards. We use the resharding flow +provided in the [local examples](../../../../get-started/local/) and show the relevant snippets from the topo for each step +in the workflow. + +{{< info >}} +Items in italics are topo keys and the following snippet the value of the key +{{< /info >}} + +## 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 + +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. + +*global/keyspaces/customer/shards/0/Shard* + +```proto +primary_alias:{cell:"zone1" uid:200} +primary_term_start_time:{seconds:1627465761 nanoseconds:600070156} +is_primary_serving:true +``` + +
+ +*global/keyspaces/customer/shards/80-/Shard* + +```proto +primary_alias:{cell:"zone1" uid:400} +primary_term_start_time:{seconds:1627465833 nanoseconds:536524508} +key_range:{start:"\x80"} +``` + +
+ +*zone1/keyspaces/customer/SrvKeyspace* + +```proto +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) + +Shard `0` still has the `is_primary_serving` set as true. The primary partition is still the same. + +The replica partition has the following changes: + +* Two more shard_references for `-80` and `80-` +* Key ranges are specified for these shards +* The key range for shard `0` has been removed +* `query_service_disabled` is set to true for shard `0` + +*global/keyspaces/customer/shards/0/Shard* + +```proto +primary_alias:{cell:"zone1" uid:200} +primary_term_start_time:{seconds:1627466189 nanoseconds:587021377} +is_primary_serving:true +``` + +
+ +*global/keyspaces/customer/shards/80-/Shard* + +```proto +primary_alias:{cell:"zone1" uid:400} +primary_term_start_time:{seconds:1627466263 nanoseconds:16201490} +key_range:{start:"\x80"}`` +``` + +
+ +_zone1/keyspaces/customer/SrvKeyspace_ + +```proto +partitions:{served_type:PRIMARY shard_references:{name:"0"}} + +partitions:{served_type:REPLICA + shard_references:{name:"-80" key_range:{end:"\x80"}} + shard_references:{name:"80-" key_range:{start:"\x80"}} + shard_tablet_controls:{name:"0" query_service_disabled:true} + shard_tablet_controls:{name:"-80" key_range:{end:"\x80"}} + shard_tablet_controls:{name:"80-" key_range:{start:"\x80"}} +} +``` + +
+ +#### 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-` +* In the primary partition the shards `-80` and `80-` are added with their associated key ranges +* In the primary partition the key range for shard `0` is removed +* The replica partition remains the same as in the previous step + +*global/keyspaces/customer/shards/0/Shard* + +```proto +primary_alias:{cell:"zone1" uid:200} +primary_term_start_time:{seconds:1627466636 nanoseconds:405646818} +``` + +
+ +*global/keyspaces/customer/shards/80-/Shard* + +```proto +primary_alias:{cell:"zone1" uid:400} +primary_term_start_time:{seconds:1627466710 nanoseconds:579634511} +key_range:{start:"\x80"} +is_primary_serving:true +``` + +
+ +*zone1/keyspaces/customer/SrvKeyspace* + +```proto +partitions:{served_type:PRIMARY + shard_references:{name:"-80" key_range:{end:"\x80"}} + shard_references:{name:"80-" + key_range:{start:"\x80"}} +} {name:"0"} + +partitions:{served_type:REPLICA + shard_references:{name:"-80" key_range:{end:"\x80"}} + shard_references:{name:"80-" key_range:{start:"\x80"}}} + shard_tablet_controls:{name:"0" query_service_disabled:true} + shard_tablet_controls:{name:"-80" key_range:{end:"\x80"}} + shard_tablet_controls:{name:"80-" key_range:{start:"\x80"}} +} +``` + +## What Happens When a MoveTables Workflow Is Cutover + +#### Before MoveTables Is Initiated + +The [`VSchema`](../../../features/vschema/) for the source keyspace contains the table name, so vtgate routes queries to that +keyspace. + +#### During MoveTables + +Both the source and target now contain the tables and both [`VSchemas`](../../../features/vschema/) refer to them. However we +have routing rules that map the tables for each tablet type from the target keyspace to the source keyspace. + +*global/RoutingRules* + +```proto +rules:{from_table:"customer" to_tables:"commerce.customer"} +rules:{from_table:"customer.customer" to_tables:"commerce.customer"} +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 + +The routing rules for replica targeted reads are updated to map the table on the source to the target. + +*global/RoutingRules* + +```proto +rules:{from_table:"customer.customer" to_tables:"commerce.customer"} rules:{from_table:"commerce.customer@replica" to_tables:"customer.customer"} +rules:{from_table:"customer" to_tables:"commerce.customer"} +rules:{from_table:"customer@replica" to_tables:"customer.customer"} +``` + +
+ +#### 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 +old/inactive shards. + +*global/RoutingRules* + +```proto +rules:{from_table:"commerce.customer@replica" to_tables:"customer.customer"} +rules:{from_table:"customer.customer@replica" to_tables:"customer.customer"} +rules:{from_table:"commerce.customer" to_tables:"customer.customer"} +rules:{from_table:"customer" to_tables:"customer.customer"} +``` + +
+ +*global/keyspaces/commerce/shards/0/Shard* + +```proto +primary_alias:{cell:"zone1" uid:100} +primary_term_start_time:{seconds:1627477340 nanoseconds:740407602} +tablet_controls:{tablet_type:PRIMARY denylisted_tables:"customer"} +is_primary_serving:true +``` + +# Miscellaneous Notes + +* In VReplication workflows, cutovers are performed manually by the user executing the `SwitchTraffic` and `ReverseTraffic` +actions e.g. for a [`MoveTables`](../../movetables/) or [`Reshard`](../../reshard/) vtctl +client command. +* When traffic for `REPLICA` and `RDONLY` tablets is switched not all read traffic is switched: primary/default reads will +still be served from the source shards, until `PRIMARY` tablet traffic is also switched. diff --git a/content/en/docs/19.0/reference/vreplication/internal/keys.md b/content/en/docs/19.0/reference/vreplication/internal/keys.md new file mode 100644 index 000000000..6cb62f6f1 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/internal/keys.md @@ -0,0 +1,459 @@ +--- +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 + +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 +rows from the source table to the target table, as well as identify binary log events from the source tablet and +apply them to the target table. To that effect, VReplication needs to be able to uniquely identify rows, so that it +can apply a specific `UPDATE` on the correct row, or so that it knows that all rows _up to a given row_ have been copied. + +Thus each row needs to be uniquely identifiable. In the relational model, this is trivially done by utilizing a `UNIQUE KEY`s, +preferably `PRIMARY KEY`s. A `UNIQUE KEY` made up of non-`NULL`able columns is considered a `PRIMARY KEY` equivalent (PKE) +for this purpose. + +Typically, both the source and the target tables have a similar structure and the same keys. + +In fact, in the most common use case, both tables will have the same `PRIMARY KEY` covering the same set of columns in +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? + +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` +able, then a `UNIQUE KEY` that includes that column is not eligible. + +`PRIMARY KEY`s are by definition always non-`NULL`able. A `PRIMARY KEY` (PK) is typically the best choice. It gives best +iteration/read performance on InnoDB tables, as those are clustered by PK (index organized tables). + +`PRIMARY KEY` aside, `VReplication` prioritizes keys that utilize e.g. integers rather than characters, and more generally +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 + +VReplication needs to be able to determine, given a row in the source table, which row it maps to in the target table. + +In the case both tables share the same `PRIMARY KEY`, the answer is trivial: given a row from the source table, take the +PK column values (say the table has `PRIMARY KEY(col1, col2)`), and compare with/apply to the target table via +`... WHERE col1= AND col2=`. + +However, other scenarios are also valid. Consider an OnlineDDL operation that modifies the `PRIMARY KEY` as +follows: `DROP PRIMARY KEY, ADD PRIMARY KEY(col1)`. On the source table, a row is identified by `col1, col2`. On the +target table, a row is only identifiable by `col1`. This scenario still feels comfortable: all we need to do when we +apply e.g. an `UPDATE` statement on the target table is to drop `col2` from the statement: `... WHERE col1=`. + +_Note that it is the user's responsibility to make sure the data will comply with the new constraints. If not, +VReplication will fail the operation._ + +But consider the opposite case, there's a `PRIMARY KEY(col1)` and an OnlineDDL operation turns it into +`PRIMARY KEY(col1, col2)`. Now we need to apply changes using `... WHERE col1= AND col2=`. But `col2` is +not part of the source `PRIMARY KEY`. + +An extreme case is when the keys on the source table and the target table do not share _any columns_ between them. Say +the source table has `PRIMARY KEY(col1)` and the target table has `PRIMARY KEY(col2)` and with no other potential keys. +We still need to identify which row in the source table maps to which row in the target table. VReplication still supports +this scenario. + +Yet another complication is when columns are renamed along the way. Consider an +`ALTER TABLE CHANGE COLUMN col2 col_two INT UNSIGNED ...` statement. A row on the source table is identified by +`col1, col2`, but on the target table it is identified by `col1, col_two`. + +Let's now discuss what the exact requirements are for unique keys, and then discuss the implementation. + +## Requirements + +To be able to create a VReplication stream between the source table and target table: + +- The source table must have a non-`NULL`able `UNIQUE/PRIMARY` key (PK or PKE) whose columns all exist in the target + table (possibly under different names) +- The target table must have a non-`NULL`able `UNIQUE/PRIMARY` key whose columns all exist in the source table (possibly + under different names) +- Except in the trivial case where both tables share the same `PRIMARY KEY` (of the same columns in the same order), + VReplication can automatically determine which keys to utilize (more on this later) + +To clarify, it is **OK** if: + +- Keys in the source table and the target table go by different names +- Chosen key in the source table and chosen key in the target table do not share any columns +- Chosen key in the source table and chosen key in the target table share some or all columns +- Chosen key in the source table and chosen key in the target table share some or all columns, but in a different order +- There are keys in the source table that cover columns not present in the target table +- There are keys in the target table that cover columns not present in the source table +- There are `NULL`able columns in the source and the target table +- There are `NULL`able keys in the source and the target table + +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 + +#### Source Table and Target Table Are the Same + +```sql +CREATE TABLE `entry` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) +) +``` + +
+ +The above is a trivial scenario. + +#### Source Table and Target table Share the Same PRIMARY KEY + +```sql +CREATE TABLE `source` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int, + PRIMARY KEY (`id`), + KEY ts_idx(`ts`) +) + +CREATE TABLE `target` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) +) +``` + +
+ +The differences in structure are interesting but irrelevant to VReplication's ability to copy the data. + +#### Subset PRIMARY KEY + +```sql +CREATE TABLE `source` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`, `customer_id`) +) + +CREATE TABLE `target` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) +) +``` + +
+ +#### Superset PRIMARY KEY + +```sql +CREATE TABLE `source` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) +) + +CREATE TABLE `target` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`, `customer_id`) +) +``` + +
+ +#### Different PRIMARY KEYs + +```sql +CREATE TABLE `source` ( + `id` int NOT NULL, + `uuid` varchar(40) NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) +) + +CREATE TABLE `target` ( + `id` int NOT NULL, + `uuid` varchar(40) NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`uuid`) +) +``` + +
+ +No columns are shared between the `PRIMARY KEY`s in the above. However: + +- `id`, covered by `source`'s PK, is found in `target` +- `uuid`, covered by `target`'s PK, is found in `source` + +#### Mixed Keys + +```sql +CREATE TABLE `source` ( + `uuid` varchar(40) NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`uuid`) +) + +CREATE TABLE `target` ( + `id` int NOT NULL, + `uuid` varchar(40) NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) + UNIQUE KEY uuid_idx(`uuid`) +) +``` + +
+ +The only eligible solution in the above is: + +- Use `source`'s `PRIMARY KEY` (the column `uuid` is found in `target`) +- Use `target`'s `uuid_idx` key (again using column `uuid` which is found in `source`). + +`target`'s `PRIMARY KEY` is not valid because the covered column `id` does not exist in `source`. + +Incidentally, in the above, the chosen keys differ by name, but share the same columns (`uuid`). + +### Examples of Invalid Cases + +#### NULLable Columns + +```sql +CREATE TABLE `source` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) +) + +CREATE TABLE `target` ( + `id` int NOT NULL, + `uuid` varchar(40) DEFAULT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + UNIQUE KEY (`uuid`) +) +``` + +
+ +The only `UNIQUE KEY` on `target` is `NULL`able, hence _not_ eligible. + +#### Missing Columns + +```sql +CREATE TABLE `source` ( + `uuid` varchar(40) NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`uuid`) +) + +CREATE TABLE `target` ( + `id` int NOT NULL, + `uuid` varchar(40) NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + `customer_id` int NOT NULL, + PRIMARY KEY (`id`) +) +``` + +
+ +`target` only has one possible key, the `PRIMARY KEY`, covering `id`. But `id` is not found in `source`. + +## 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. + +In all other cases, VReplication must determine which keys are involved and which ones to use. + +### Example 1 + +Let's begin again as a trivial example, both tables have same `PRIMARY KEY`s: + +```sql +CREATE TABLE `corder` ( + `order_id` bigint NOT NULL AUTO_INCREMENT, + `customer_id` bigint DEFAULT NULL, + `sku` varbinary(128) DEFAULT NULL, + `price` bigint DEFAULT NULL, + PRIMARY KEY (`order_id`) +) +``` + +
+ +And even though we don't _have to_, here's how we could manually configure the VReplication workflow definition +(prettified for readability): + +```proto +keyspace:"commerce" shard:"0" filter:{ + rules:{ + match:"corder" + filter:"select `order_id` as `order_id`, `customer_id` as `customer_id`, `sku` as `sku`, `price` as `price` from `corder`" + source_unique_key_columns:"order_id" + target_unique_key_columns:"order_id" + source_unique_key_target_columns:"order_id" + } +} +``` + +
+ +In the above: + +- `source_unique_key_columns` is the (comma delimited) list of columns covered by the chosen key on source table +- `target_unique_key_columns` is the (comma delimited) list of columns covered by the chosen key on target table +- `source_unique_key_target_columns` is the (comma delimited) list of column names in target table, which map + to `source_unique_key_columns`. This mapping is necessary because columns may change their names. + +### Example 2 + +Again both the source and the target table share same `PRIMARY KEY`, but this time it covers two columns: + +```sql +CREATE TABLE `shipment` ( + `order_id` int NOT NULL, + `customer_id` int NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + PRIMARY KEY (`order_id`,`customer_id`) +) +``` + +```proto +keyspace:"commerce" shard:"0" filter:{ + rules:{ + match:"shipment" + filter:"select `order_id` as `order_id`, `customer_id` as `customer_id`, `ts` as `ts` from `shipment`" + source_unique_key_columns:"order_id,customer_id" + target_unique_key_columns:"order_id,customer_id" + source_unique_key_target_columns:"order_id,customer_id" + } +} +``` + +
+ +Not much changed from the previous example, just note how we comma separate `"order_id,customer_id"`. + +### Example 3 + +Continuing the previous example, we now rename a column the target table: + +```sql +CREATE TABLE `shipment` ( + `order_id` int NOT NULL, + `cust_id` int NOT NULL, + `ts` timestamp NULL DEFAULT NULL, + PRIMARY KEY (`order_id`,`cust_id`) +) +``` + +```proto +keyspace:"commerce" shard:"0" filter:{ + rules:{ + match:"shipment" + filter:"select `order_id` as `order_id`, `customer_id` as `cust_id`, `ts` as `ts` from `shipment`" + source_unique_key_columns:"order_id,customer_id" + target_unique_key_columns:"order_id,cust_id" + source_unique_key_target_columns:"order_id,cust_id" + } +} +``` + +
+ +Note: + +- `source_unique_key_columns` indicates the names of columns on the source table +- `target_unique_key_columns` indicates the names of columns on the target table +- `source_unique_key_target_columns` repeats `source_unique_key_columns`, but replaces `customer_id` with `cust_id` + +## Automation + +OnlineDDL has a mechanism to automatically analyze the differences between source and target tables, evaluate eligible +keys, choose the best keys on source and target tables, and populate the filter's +`source_unique_key_columns`, `target_unique_key_columns`, and `source_unique_key_target_columns` fields. Indeed, +OnlineDDL operations are most susceptible to differences in keys. The user can also supply their chosen values as an +override — using those fields in the workflow definition — in the rare case it's needed. + +VReplication more broadly will automatically use the most efficient `PRIMARY KEY` equivalent or PKE (non-`NULL`able unique +key) when there's no defined `PRIMARY KEY` on the table. + +## Implementation + +At a high level, this is how VReplication is able to work with different keys/columns between the source and target. + +Originally, VReplication was only designed to work with identical `PRIMARY KEY`s. If not specified, VReplication assumed +the source table's `PRIMARY KEY` _can be used_ on the target table, and that the target table's `PRIMARY KEY` is applied +to the source table. If not, it would error out and the workflow would fail. + +With the introduction of mechanisms to automatically determine the optimal key to use and of +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 + +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 +a `PRIMARY KEY` or pkColumns, etc., it may refer to a non-PK Unique Key (PKE). + +### Streamer + +Streaming is done using the `source_unique_key_columns` value if present. When present, `rowstreamer` trusts the +information in `source_unique_key_columns` to be correct. It does not validate that there is indeed a valid unique key +covering those columns, it only validates that the columns exist. When a `source_unique_key_columns` value is not +present, `rowstreamer` uses the `PRIMARY KEY` columns if they exist, otherwise it will determine the best +available `PRIMARY KEY` equivalent if one exists, and lastly if none of these are available it will use all of the +columns in the table. + +The streamer iterates the table by the chosen index's column order. It then tracks its progress in `lastPk` as if this +was indeed a true `PRIMARY KEY`. + +### Copier + +VCopier receives rows from the `rowstreamer` in the chosen index's column order. It complies with the streamer's ordering. +When tracking progress in `_vt.copy_state` it uses `lastPk` values from the streamer, which means it uses the same index +columns as the streamer in that order. + +### Player + +VPlayer adheres to both `source_unique_key_columns` and `target_unique_key_columns` when present. If not present, again +it attempts to use the `PRIMARY KEY` columns if they exist, otherwise it will determine the best available `PRIMARY KEY` +equivalent if one exists, and lastly if none of these are available it will use all of the columns in the table. + +- `TablePlan`'s `isOutsidePKRange()` function needs to compare values according to `rowstreamer`'s ordering, therefore + uses the chosen index columns in order. +- `tablePlanBuilder`'s `generateWhere()` function uses the target table's `target_unique_key_columns`, and then also + appends any supplemental columns from `source_unique_key_target_columns` not included in `target_unique_key_columns` + when they are present. If not present, again it attempts to use the `PRIMARY KEY` columns if they exist, otherwise it + will determine the best available `PRIMARY KEY` equivalent if one exists, and lastly if none of these are available it + will use all of the columns in the table. diff --git a/content/en/docs/19.0/reference/vreplication/internal/life-of-a-stream.md b/content/en/docs/19.0/reference/vreplication/internal/life-of-a-stream.md new file mode 100644 index 000000000..278635c87 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/internal/life-of-a-stream.md @@ -0,0 +1,174 @@ +--- +title: Life of a Stream +description: How VReplication replicates data +weight: 1 +aliases: ['/docs/design-docs/vreplication/life-of-a-stream/'] +--- + +### Introduction + +When a VReplication workflow runs, data is copied from source to target shards. Each target `PRIMARY` tablet runs one +vreplication stream (`vstream`) for each source shard that the target's +[keyrange](../../../features/sharding/#key-ranges-and-partitions) overlaps with. + +The diagram below outlines how one such stream operates. VReplication can be asked to start from a specific +[`GTID`](https://dev.mysql.com/doc/refman/en/replication-gtids-concepts.html) or from the start. When starting from a +[`GTID`](https://dev.mysql.com/doc/refman/en/replication-gtids-concepts.html) the _replication_ mode is used where it +streams events from the binlog. + +![VReplication Flow](/img/VReplicationFlow.png) + +#### 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 +binlogs are no longer available. + +So a _copy/catchup_ mode is initiated first: data in the tables are copied over in a consistent manner using bulk +inserts. Once we have copied enough data so that we are close enough to the current position (when replication lag is +low) it switches over to, and forever stays in, the _replication_ mode. All future replication is done only by +streaming binlog events. + +While we may have multiple database sources in a workflow each `vstream` has just one source and one target. The source is +always a `vttablet` (and hence one `mysqld` instance). The target could be another `vttablet` (when resharding) or a +streaming gRPC response (for [`vtgate` `vstream` API](../../vstream/) clients). + +#### Transformation and Filtering + +Note that for all steps the data selected from the source will only be from the tables specified +in the [`Match`](https://github.com/vitessio/vitess/blob/main/proto/binlogdata.proto#LL128C5) field of the Rule +specification of the VReplication workflow. Furthermore, if a +[`Filter`](https://github.com/vitessio/vitess/blob/main/proto/binlogdata.proto#LL133C5) is specified for a table it will +be applied before being sent to the target. Columns may also be transformed based on the Filter’s `SELECT` clause. + +#### Source and Sink + +Each stream has two actors: the target initiates streaming by making gRPC calls to the source tablet and the source +tablet sources the data by connecting to its underlying `mysqld` server as a replica (while replicating) or using SQL +queries (in the copy phase) and streams it to the target. The target takes appropriate action: in case of resharding it +will convert the events into CRUD SQL statements and apply them to the target database. In case of [`vtgate` `vstream` +API](../../vstream/) clients the events are forwarded by `vtgate` to the client. + +Note that the target always pulls data. If the source pushes data, there are chances of buffer overruns if the target is +not able to process them in time. For example, in resharding workflows we need to convert the events to SQL `INSERT` +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 + +#### Replicate + +This is the easiest to understand. The source stream just acts like a MySQL replica and processes events as they are +received. Events, after any necessary filtering and transformation, are sent to the target. Replication runs +continuously with short sleeps when there are no more events to source. Periodic heartbeats are sent to the target to +signal liveness. You will see this reflected with the `Running` state for the workflow. + +#### Initialize + +Initialize is called at the start of the copy phase. For each table to be copied an entry is created in the internal +`_vt.copy_state` table with a null primary key (PK). As each table copy is completed the related entries are deleted +and when there are no more entries for this workflow the copy phase is considered complete and the workflow moves into +the replication mode which you will see reflected with the `Running` state for the workflow. + +#### Copy + +Copy works on one table at a time. The source selects a set of rows from the table, for primary keys greater than the +ones copied so far, using a consistent snapshot. This results in a stream of rows to be sent to the target which +generates a bulk `INSERT` for these rows. You will see this reflected with the `Copying` state for the workflow. + +However, there are a couple of factors which complicate our story: + +* Each copy selects all rows until the current position of the binlog, but, +* Since transactions continue to be applied (presuming the database is online) the GTID position is continuously +moving forward + +Consider this example: + +We have two tables `X` and `Y`. Each table has 20 rows and we copy 10 rows at a time. (The queries below simplified +for readability). + +The queries for the copy phase of `X` will be: + +```sql +T1: select * from X where pk > 0 limit 10; GTID: 100, Last PK 10 + + send rows to target + +T2: select * from X where pk > 10 limit 10; GTID: 110, Last PK 20 + + send rows to target +``` + +
+ +There is a gotcha here: onsider that there are 10 new transactions or GTIDs between times T1 and T2. Some of these +can potentially modify the rows returned from the query at T1. Hence if we just return the rows from T2 (which have +only rows from PK 11 to 20) then we will have an inconsistent state on the target: the updates to rows with PK +between 1 and 10 will not be present. + +This means that we need to first stream the events between GTIDs 100 and 110 for primary keys between 1 and 10 first +and then do the second select: + +```sql +T1: select * from X where pk > 0 limit 10; GTID: 100, Last PK 10 + + send rows to target + +T2: replicate from 100 to current position (110 from previous example), + + only pass events for pks 1 to 10 of X + +T3: select * from X where pk > 10 limit 10; GTID: 112, Last PK 20 + + send rows to target +``` + +
+ +Another gotcha: note that at time T3 when we selected the PKs from 11 to 20 the GTID position could have moved further! +This could be due to transactions that were applied between T2 and T3. So if we just applied the rows from T3 we would +still have an inconsistent state, if transactions 111 and 112 affected the rows from pks 1 to 10. + +This leads us to the following flow: + +```sql +T1: select * from X where pk > 0 limit 10; GTID: 100, Last PK 10 + + send rows to target + +T2: replicate from 100 to current position (110 from previous example), + + only pass events for pks 1 to 10 + +T3: select * from X where pk > 10 limit 10; GTID: 112, Last PK 20 + +T4: replicate from 111 to 112 + + only pass events for pks 1 to 10 + +T5: Send rows for pks 11 to 20 to target +``` + +
+ +This flow actually works and is the one used in Vitess VReplication! + +The transactions to be applied at T1 can take a long time (due to the bulk inserts). T3 (which is just a snapshot) is +quick. So the position can diverge much more at T2 than at T4. Hence, we call step T2 "Catchup" and step T4 +"Fast Forward". + +#### Catchup + +As detailed above the catchup phase runs between copy phase cycles (time limited by the +[`vreplication_copy_phase_max_duration`](../../flags/#vreplication_copy_phase_duration) flag). During the copy phase the +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 + +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. + +Finally once we have finished copying all the tables we proceed to the replicate or `Running` phase until our job is done: +for example if we have resharded and switched over the reads and writes to the new shards or when the +[`vstream` API](../../vstream/) client closes its connection. diff --git a/content/en/docs/19.0/reference/vreplication/internal/tracker.md b/content/en/docs/19.0/reference/vreplication/internal/tracker.md new file mode 100644 index 000000000..1aa688c12 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/internal/tracker.md @@ -0,0 +1,184 @@ +--- +title: Schema Tracker +description: Tracking schema changes in VStreams +aliases: [] +weight: 4 +aliases: ['/user-guide/update-stream', '/docs/design-docs/vreplication/vstream/tracker/'] +--- + +# Tracking Schema Changes in VStreams + +## Motivation + +Currently, vstreams work with a single (the latest or current) database schema. On every DDL the schema engine reloads the +schema from the database engine. + +All vstreams on a tablet share a common schema engine. VStreams that are lagging can see a more recent schema than when +the older binlog events occurred. So the lagging vstreams will see an incorrect version of the schema in case DDLs were +applied in between that affect the schema of the tables involved in those lagging events. + +In addition, reloading schemas is an expensive operation. If there are multiple vstreams them each of them will separately +receive a DDL event resulting in multiple reloads for the same DDL. + +{{< info >}} +For full functionality, schema tracking relies on these non-default Vitess `vttablet` flags: +[`--watch_replication_stream`](../../flags/#watch_replication_stream) and +[`--track_schema_versions`](../../flags/#track_schema_versions). Specifically, performing a vstream from a non-PRIMARY +tablet while concurrently making DDL changes to the keyspace without one or both of these tablet options could result in +incorrect vstream results. +{{< /info >}} + +## Goals + +1. Provide a mechanism for maintaining versions of the schema +2. Reduce the number of redundant schema loads + +## Model + +We add a new `schema_version` table in the internal `_vt` database with columns, including, the `GTID` position, the +schema as of that position, and the DDL that led to this schema. Inserting into this table generates a `version` event +in the vstream. + +## Actors + +#### Schema Engine + +Schema engine gets the schema from the database and only keeps the last (latest) copy it loaded. It notifies subscribers +if the schema changes. It polls for the latest schema at intervals or can be explicitly requested to load the schema for +a tablet using the [`ReloadSchemaKeyspace`](../../../programs/vtctl/schema-version-permissions/#reloadschemakeyspace) +vtctl client command. + +#### Replication Watcher + +Replication watcher is a separate vstream that is started by the tabletserver. It notifies subscribers when it encounters +a DDL in the workflow stream. + +#### Version Tracker + +Version tracker runs on the `PRIMARY` tablet. It subscribes to the replication watcher and inserts a new row into the +`_vt.schema_version` table with the latest schema. + +#### Version Historian + +Version historian runs on both `PRIMARY` and `REPLICA` tablets and handles DDL events. For a given `GTID` it looks in its +cache to check if it has a valid schema for that `GTID`. If not, it looks up the in the `schema_version` table on `REPLICA` +tablet. If no schema is found then it provides the latest schema -- which is updated by subscribing to the schema engine’s +change notification. + +### Notes + +- Schema Engine is an existing service +- Replication Watcher is used as an optional vstream that the user can run. It doesn’t do anything user specific: it is only +used for the side-effect that a vstream loads the schema on a DDL to proactively load the latest schema + +## Basic Flow for Version Tracking + +### Primary + +#### Version Tracker: + +1. When the primary comes up the replication watcher (a vstream) is started from the current `GTID` position. The +tracker subscribes to the watcher. +1. Say, a DDL is applied +1. The watcher vstream sees the DDL and +1. Asks the schema engine to reload the schema, also providing the corresponding `GTID` position +1. Notifies the tracker of a schema change +1. Tracker stores its latest schema into the `_vt.schema_version` table associated with the given `GTID` and DDL + +#### Historian/VStreams: + +1. Historian warms its cache from the `_vt.schema_version` table when it starts +2. When the tracker inserts the latest schema into `_vt.schema_version` table, the vstream converts it into a (new) + version event +3. For every version event the vstream registers it with the historian +4. On the version event, the tracker loads the new row from the `_vt.schema_version` table +5. When a vstream needs a new `TableMap` event it asks the historian for it along with the corresponding `GTID` +6. Historian looks in its cache for a schema version for that `GTID`. If not present it provides the latest schema it + has received from the schema engine + +#### Replica + +1. Version tracker does not run: the tracker can only store versions on the `PRIMARY` since it requires writing to the +database +2. Historian functionality is identical to that on the `PRIMARY` + +## Flags + +### Primary + +Schema version snapshots are stored only on the `PRIMARY`. This is done when the Replication Watcher gets a DDL event +resulting in a `SchemaUpdated()` call. There are two independent flows here: + +1. Replication Watcher is running +2. Schema snapshots are saved to `_vt.schema_version` when `SchemaUpdated()` is called + +Point 2 is performed only when the [`--track_schema_versions`](../../flags/#track_schema_versions) `vttablet` flag is enabled. +This implies that #1 also has to happen when [`--track_schema_versions`](../../flags/#track_schema_versions) is enabled +independently of the [`--watch_replication_stream`](../../flags/#watch_replication_stream) flag. + +However if the [`--watch_replication_stream`](../../flags/#watch_replication_stream) flag is enabled but +[`--track_schema_versions`](../../flags/#track_schema_versions) is disabled we still need to run the Replication +Watcher since the user has requested it, but we do not store any schema versions. + +So the logic is: + +1. WatchReplication==true \ + => Replication Watcher is running + +2. TrackSchemaVersions==false + => SchemaUpdated is a noop + +3. TrackSchemaVersions=true + => Replication Watcher is running \ + => SchemaUpdated is handled + +The historian behavior is identical to that of the replica: of course if versions are not stored in `_vt.schema_versions` +it will always provide the latest version of the schema. + +### Replica + +Schema versions are never stored directly on `REPLICA` tablets, so SchemaUpdated is always a noop. Versions are provided +as appropriate by the historian. The historian provides the latest schema if there is no appropriate version. + +So the logic is: + +1. WatchReplication==true \ + => Replication Watcher is running + +2. TrackSchemaVersions==false || true //noop \ + => Historian tries to get appropriate schema version + +## Caveat + +Only best-effort versioning can be provided due to races between DDLs and DMLs. Some examples below: + +### Situation 1 + +If multiple DDLs are applied in a quick sequence we can end up with the following binlog scenario: + +```text +T1: DDL 1 on table1 + +T2: DDL 2 on table1 + +T3: Version Event DDL1 // gets written because of the time taken by tracker processing DDL1 + +T4: DML1 on table1 + +T5: Version Event DDL2 // gets written AFTER DML1 +``` + +
+ +So now on the `REPLICA`, at T4, the version historian will incorrectly provide the schema from T1 after DDL1 was applied. + +### Situation 2 + +If version tracking is turned off on the `PRIMARY` for some time, correct versions may not be available to the historian +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 + +- 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/19.0/reference/vreplication/internal/vstream-skew-detection.md b/content/en/docs/19.0/reference/vreplication/internal/vstream-skew-detection.md new file mode 100644 index 000000000..dd444246a --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/internal/vstream-skew-detection.md @@ -0,0 +1,84 @@ +--- +title: VStream Skew Minimization +description: Aligning streams from different shards in the VStream API +weight: 7 +aliases: ['/docs/design-docs/vreplication/vstream/skew-detection/'] +--- + +## VStream Skew Detection + +### Motivation + +When the [VStream API](../../vstream/) is streaming from multiple shards we have multiple sources of events: one `PRIMARY` +or `REPLICA` tablet for each shard in the provided [`VGTID`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VGtid). +The rate at which the events will be streamed from the underlying sources can vary depending on various factors, such as: + +* The replication lag on the source tablets (if a `REPLICA` tablet is selected as the source for the vstream) +* The CPU load on the source tablet +* Possible network partitions or network delays + +This can result in the events in the vstream from some shards being well ahead of other shards. So, for example, if a +row moves from the faster shard to a slower shard we might see the `DELETE` event in the vstream from the faster shard +long before the `INSERT` from the second. This would result in the row going "invisible" for the duration of the skew. +This can affect the user experience in applications where the vstream events are used to refresh a UI, for example. + +For most applications where [VStream API](../../vstream/) events feed into change data capture systems for auditing or +reporting purposes these delays may be acceptable. However, for applications which are using these events for user-facing +functions this can cause unexpected behavior. See https://github.com/vitessio/vitess/issues/7402 for one such case. + +### Goal + +It is not practically possible to provide exact ordering of events across Vitess shards. The [VStream API](../../vstream/) +will inherently stream events from one shard independently of another. However, vstream events +([`VEvent`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VEvent)) do keep track of the binlog event +timestamps which we can use to loosely coordinate the streams. Since binlog timestamp granularity is only to the nearest +second, and we attempt to align the streams to within a second. + +### Implementation + +The skew minimization feature adds a [`MinimizeSkew` flag](../../vstream/#minimizeskew) that the client can set. This flag +enables skew detection between the various streams. Once a skew is detected, events for streams that are ahead are held back +until the lagging streams catch up causing the skew to reach an acceptable level. + +Each vstream event ([`VEvent`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VEvent)) contains two timestamps: +one when the database transaction occurred, and the other the current time on the source tablet where the +[`VEvent`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VEvent) was created. This lets us compute how far in +the past the event we just received was created. We use this to determine which shard has the most recent event and which one +has the oldest. Note that for shards where there is no activity, the vstreamer sends a heartbeat event every second and the +transaction time for a heartbeat is the same as the current time on the source. (These heartbeats are not forwarded to clients +in the vstream since they are synthetic/internal VReplication events.) + +If the difference between the fastest and slowest streams is greater than a threshold, we declare that we have detected +a skew. MySQL binlogs store the transaction timestamp in seconds. Also, on the `vtgate` serving the vstream, we adjust +this time for clock skews between the `vtgate` and the source tablet's `mysqld` server. When the user sets the `MinimizeSkew` +flag we want to keep the events across shards within the same second: each transaction timestamp is within 1 second of each +other. To account for rounding-off of the transaction timestamp and the clock-skew we set the threshold to be 2 seconds, +instead of 1 second, so that we don't keep stalling the streams due to cumulative round-offs. + +### Possible Unexpected Behavior + +If there are no events for a second in a shard then a heartbeat is sent. On receiving a heartbeat we reset the skew. +This is necessary to avoid shards with no events starving other shards. The current logic will align streams only if +they are all getting events faster than the heartbeat frequency. + +This means that we cannot guarantee the skew alignment feature will work as expected in certain conditions. This could +happen mainly while streaming from `REPLICA` tablets with high replication lag, say, due to high write QPS or a network +partition. + +Thus it is recommended that you stream from `PRIMARY` tablets when using the [VStream feature](../../vstream/). +Note, however, that even `PRIMARY` tablets with skewed loads could potentially trigger such a situation. + +### API + +This is how you would turn on the skew detection and alignment feature in a [VStream](../../vstream/) client: + +```go + import vtgatepb "vitess.io/vitess/go/vt/proto/vtgate" + ... + ... + flags := &vtgatepb.VStreamFlags{}; + flags.MinimizeSkew = true; + + reader, err := conn.VStream(ctx, topodatapb.TabletType_PRIMARY, vgtid, filter, flags) + +``` diff --git a/content/en/docs/19.0/reference/vreplication/internal/vstream-stream-migration.md b/content/en/docs/19.0/reference/vreplication/internal/vstream-stream-migration.md new file mode 100644 index 000000000..f22aea00f --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/internal/vstream-stream-migration.md @@ -0,0 +1,82 @@ +--- +title: VStream API and Resharding +description: How VStream API handles a reshard +weight: 8 +aliases: ['/docs/design-docs/vreplication/vstream/stream-migration/'] +--- + +## Stream Migration on a Resharding Operation + +While subscribing to the [VStream API](../../vstream/) you need to specify the shards from which to stream events. While +streaming it is possible that the underlying keyspace is resharded. Thus some or all of the shards which were originally +specified may be replaced by new shards after the resharding operation is completed. + +Stream migration logic within VReplication handles this transparently within `vtgate`. The Event streaming will be paused +momentarily during the actual cutover (when writes are switched) and you will start getting the events +([`VEvent`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VEvent)) (and updated +[`VGTID`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VGtid)s) for the new set of shards once the cutover +is completed. + +### An Illustration + +Here is a sample session using the scripts from the [local example](../../../../get-started/local). + +Run the steps up to and including `205_clean_commerce.sh`. Now start a [VStream API](../../vstream/) client in a +separate terminal to stream events from the `customer` table in the `customer` keyspace, which is currently unsharded. + +```json +{ + ShardGtids: []*binlogdatapb.ShardGtid{ + { + Keyspace: "customer", + Shard: "0", + }, + }, +} +``` + +
+ +Initial events will be streamed: + +```proto +[type:BEGIN type:FIELD field_event: fields: > ] +[type:VGTID vgtid: > ] +[type:ROW row_event: > > type:ROW row_event: > > type:ROW row_event: > > type:ROW row_event: > > type:ROW row_event: > > type:VGTID vgtid: > > > > type:COMMIT ] +[type:BEGIN type:VGTID vgtid: > type:COMMIT ] +``` + +
+ +Now run the resharding scripts and switch reads (steps/scripts 301, 302, 303, and 304). The following events are now seen: + +```proto +[type:VGTID vgtid: > type:DDL timestamp:1616748652 statement:"alter table customer change customer_id customer_id bigint not null" current_time:1616748652480051077 ] +[type:VGTID vgtid: > type:OTHER timestamp:1616748652 current_time:1616748652553883482 ] +``` + +
+ +Run the 305 step/script to switch writes. You will see that the [`VGTID`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VGtid)s) +will include the new shards `-80` and `80-` instead of `0`: + +```proto +[type:BEGIN timestamp:1616748733 current_time:1616748733480901644 type:VGTID vgtid: > type:COMMIT timestamp:1616748733 current_time:1616748733480932466 ] +[type:BEGIN timestamp:1616748733 current_time:1616748733486715446 type:VGTID vgtid: > type:COMMIT timestamp:1616748733 current_time:1616748733486749728 ] + +[type:BEGIN timestamp:1616748733 current_time:1616748733519198641 type:VGTID vgtid: shard_gtids: > type:COMMIT timestamp:1616748733 current_time:1616748733519244822 ] +[type:BEGIN timestamp:1616748733 current_time:1616748733520355854 type:VGTID vgtid: shard_gtids: > type:COMMIT timestamp:1616748733 current_time:1616748733520403210 ] +``` + +
+ +Insert new rows: this will result in row events from the new shards. Shards will only stream changes from the point of +resharding. + +```bash +$ mysql -u root --host=127.0.0.1 -P 15306 -e "insert into customer(customer_id, email) values(6,'rohit@planetscale.com'), (7, 'mlord@planetscale.com')" +``` + +```proto +[type:BEGIN timestamp:1616749631 current_time:1616749631516372189 type:FIELD timestamp:1616749631 field_event: fields: > current_time:1616749631517765487 type:ROW timestamp:1616749631 row_event: > row_changes: > > current_time:1616749631517779353 type:VGTID vgtid: shard_gtids: > type:COMMIT timestamp:1616749631 current_time:1616749631517789376 ] +``` diff --git a/content/en/docs/19.0/reference/vreplication/materialize.md b/content/en/docs/19.0/reference/vreplication/materialize.md new file mode 100644 index 000000000..4a044f274 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/materialize.md @@ -0,0 +1,106 @@ +--- +title: Materialize +description: +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 +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. + +{{< 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 >}} + +### Parameters + + +#### --cells +**optional**\ +**default** local cell + +
+ +A comma-separated list of cell names or cell aliases. This list is used by VReplication to determine which +cells should be used to pick a tablet for selecting data from the source keyspace.

+ +
+ +###### Uses + +* Improve performance by using picking a tablet in cells in network proximity with the target +* To reduce bandwidth costs by skipping cells that are in different availability zones +* Select cells where replica lags are lower + +#### --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** + +
+ +Source tablet types to replicate from (e.g. PRIMARY, REPLICA, RDONLY). The value +specified impacts [tablet selection](../tablet_selection/) for the workflow. + +
+ +###### Uses + +* To reduce the load on PRIMARY tablets by using REPLICAs or RDONLYs +* Reducing lag by pointing to PRIMARY + +#### JSON spec details +
+ +* *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 +``` +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 + +There are special commands to perform common materialization tasks and you should prefer them +to using `Materialize` directly. + +* If you just want to copy tables to a different keyspace use [MoveTables](../movetables) +* If you want to change sharding strategies use [Reshard](../reshard) instead diff --git a/content/en/docs/19.0/reference/vreplication/metrics.md b/content/en/docs/19.0/reference/vreplication/metrics.md new file mode 100644 index 000000000..46707bcc5 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/metrics.md @@ -0,0 +1,151 @@ +--- +title: Metrics +description: Metrics related to vreplication functionality +weight: 85 +--- + +VReplication exports several metrics using the expvars interface. These are available at the `/debug/vars` endpoint of vttablet's http status pages. [More details can be found here](../../features/monitoring/#3-push-based-metrics-system). + +## Target Tablet Metrics + +#### VReplicationCopyLoopCount, VReplicationCopyLoopCountTotal + +During the copy phase we run one loop of bulk copy for approximately an hour at a time (by default) before running catchup. _VReplicationCopyLoopCount_ counts the number of times this loop has run for each stream and _VReplicationCopyLoopCountTotal_ the total across all streams. + +#### VReplicationCopyRowCount, VReplicationCopyRowCountTotal + +_VReplicationCopyRowCount_ counts the number of rows copied during the copy phase per stream and _VReplicationCopyRowCountTotal_ the total across all streams. + +#### VReplicationErrors + +_VReplicationErrors_ counts the number of times errors occurred during vreplication. Errors are keyed +by the type of error. + +#### VReplicationHeartbeat + +_VReplicationHeartbeat_ records, for each stream, the timestamp sent by the last heartbeat event for that stream. + +#### VReplicationMessages + +_VReplicationMessages_ contains a stack of the last N (currently 3) messages of a vreplication stream. + +#### VReplicationPhaseTimings, VReplicationPhaseTimingsCounts, VReplicationPhaseTimingsTotal + +This metric relates to the times each phase is run during the lifetime of a stream. +_VReplicationPhaseTimings_ counts the total time taken by the runs, +VReplicationPhaseTimingsCounts the number of runs and _VReplicationPhaseTimingsTotals_ the total +runs across all streams. + +#### VReplicationTableCopyRowCounts + +_VReplicationTableCopyRowCounts_ counts the number of rows copied during the copy phase per table per stream. + +#### VReplicationTableCopyTimings + +_VReplicationTableCopyTimings_ counts the time taken per table per stream during the copy phase of the stream. Unlike _VReplicationPhaseTimings_, this metric updates continuously, rather than being set once at the end of the copy phase. + +#### VReplicationQPS + +_VReplicationQPS_ is a list of QPS values for each loop of each phase of the workflow. + +#### VReplicationQueryCount, VReplicationQueryCountTotal + +_VReplicationQueryCount_ is the total number of queries in each phase of a workflow. _VReplicationQueryCountTotal_ is the total queries across all phases and workflows. + +#### VReplicationLagSeconds, VReplicationLagSecondsMax, VReplicationLagSecondsTotal + +These metrics show the replication lag of the target stream with respect to the source stream. _VReplicationLagSeconds_ shows the current replication lag and _VReplicationLagSecondsMax_ has the maximum lag in this stream. Note that these values are only valid during the replication phase of a workflow. + +#### VReplicationSource + +Shows the keyspace and shard of the source from which this target stream is replicating + +#### VReplicationSourceTablet + +Shows the tablet from which this stream is currently replicating + +#### VReplicationStreamCount + +The number of streams running on this target + +#### VReplicationStreamState + +This shows the state of each stream. + +## Source Tablet Metrics + +#### VStreamPacketSize + +The value of the `vstream_packet_size` flag specified for this tablet + +#### VStreamerCount + +The current number of running vstreamers + +#### VStreamerErrors + +The number of errors per category across workflows + +#### VStreamersEndedWithErrors + +The total number of errors that caused a stream to stall + +#### VStreamerEventsStreamed + +The total number of events streamed by this vttablet across all workflows + +#### VStreamerCompressedTransactionsDecoded + +The total number of compressed transactions (MySQL's binlog_transaction_compression=ON) decoded by this vttablet across all workflows + +#### VStreamerNumPackets + +The total number of packets sent by this vttablet across all workflows + +#### VStreamersCreated + +The total number of vstreamers created during the lifetime of this tablet + +
+ +## Example +**A snippet from tablet 200 from the local example after running the MoveTables step** + +``` +"VReplicationCopyLoopCount": {"commerce.0.commerce2customer.1": 2}, +"VReplicationCopyLoopCountTotal": 2, +"VReplicationCopyRowCount": {"commerce.0.commerce2customer.1": 10}, +"VReplicationCopyRowCountTotal": 10, +"VReplicationErrors": {}, +"VReplicationHeartbeat": {"commerce.0.commerce2customer.1": 1618681048}, +"VReplicationMessages": {"1": "2021-04-17T19:36:13.003858838+02:00:Picked source tablet: cell:\"zone1\" uid:100 "}, +"VReplicationPhaseTimings": {"commerce.0.commerce2customer.1.catchup": 1000935083, "commerce.0.commerce2customer.1.fastforward": 15349583, "commerce.0.commerce2customer.1.copy": 63353125}, +"VReplicationPhaseTimingsCounts": {"commerce.0.commerce2customer.1.copy": 2, "commerce.0.commerce2customer.1.All": 6, "commerce.0.commerce2customer.1.catchup": 2, "commerce.0.commerce2customer.1.fastforward": 2}, +"VReplicationPhaseTimingsTotal": 1079637791, +"VReplicationQPS": {"All":[11.8,1,1.2,1.2,1,1.2,1,1.2,1,1.2,1,1.2,1.2,1,1.2,1,1.2],"Query":[11.2,1,1.2,1.2,1,1.2,1,1.2,1,1.2,1,1.2,1.2,1,1.2,1,1.2],"Transaction":[0.6,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}, +"VReplicationQueryCount": {"commerce.0.commerce2customer.1.copy": 2}, +"VReplicationQueryCountTotal": 2, +"VReplicationLagSeconds": {"commerce.0.commerce2customer.1": 0}, +"VReplicationLagSecondsMax": 0, +"VReplicationLagSecondsTotal": 0, +"VReplicationSource": {"1": "commerce/0"}, +"VReplicationSourceTablet": {"1": "cell:\"zone1\" uid:100 "}, +"VReplicationStreamCount": 1, +"VReplicationStreamState": {"commerce2customer.1": "Running"}, +"VReplicationTableCopyRowCounts": {"commerce.0.commerce2customer.1.corder": 4, "commerce.0.commerce2customer.1.customer": 2}, +"VReplicationTableCopyTimings": {"commerce.0.commerce2customer.1.customer": 6707583, "commerce.0.commerce2customer.1.corder": 13254250}, +"VStreamPacketSize": 250000, +"VStreamerCount": 0, +"VStreamerErrors": {"Catchup": 0, "Copy": 0, "Send": 0, "TablePlan": 0}, +"VStreamerEventsStreamed": 0, +"VStreamerNumPackets": 0, +"VStreamerPhaseTiming": {"TotalCount":0,"TotalTime":0,"Histograms":{}}, +"VStreamersCreated": 0, +"VStreamersEndedWithErrors": 0, +``` + +## VTGate Metrics +#### VStreamsCreated +The total number of vstreams created during the lifetime of this vtgate. +#### VStreamsLag +The difference in seconds between the current time when the vstream event was sent and the time when the binlog event occurred. \ No newline at end of file diff --git a/content/en/docs/19.0/reference/vreplication/migrate.md b/content/en/docs/19.0/reference/vreplication/migrate.md new file mode 100644 index 000000000..b7ed3cb6a --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/migrate.md @@ -0,0 +1,175 @@ +--- +title: Migrate +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 +utilized when moving Keyspaces or Tables between two separate Vitess environments. Migrate is an advantageous strategy for large sharded environments +for a few reasons: + +* Data can be migrated while the source Vitess cluster, typically the production environment, continues to serve traffic. +* Shard mapping between Source and Target Vitess clusters is handled automatically by Migrate. + * Similar to MoveTables, you may have different shard counts between the source and target Vitess clusters. +* VDiffs and read-only SQL can be performed to verify data integrity before the Migration completes. +* Migrate works as a copy of data not a move, source data remains once the Migrate completes. +* Could be used for configuring lower environments with production data. + +Please note the Migrate command works with an externally mounted source cluster. See the related [Mount command](../mount) for more information +on working with external Vitess clusters. + +#### Differences Between Migrate and MoveTables + +`Migrate` has separate semantics and behaviors from `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. + * 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`. + +The `Create` action is also modified to accommodate the external mount. The proper syntax will be highlighted below: + +``` +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). + +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 + +{{< 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. +{{< /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` +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` +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. Start the application pointed to the target Vitess Cluster. +1. Unmount the source cluster.
+`Mount -- --unmount ext1` + + +### Network Considerations + +For Migrate to function properly, you will need to ensure communication is possible between the target Vitess cluster and the source Vitess cluster. At a minimum the following network concerns must be implemented: + +* 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. + +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 +``` + +To verify the Migration you can also perform VDiff with the `--tablet_types` option: + +``` +VDiff -- --tablet_types REPLICA . +``` + +### Troubleshooting Errors + +`Migrate` fails right away with error: + +```sh +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: +* The target table has a VSchema which does not match the source VSchema +* Upload the source VSchema to the target VSchema and try the `Migrate` again + +--- + +`Migrate` fails right away with error: + +```sh +E0224 18:55:29.275019 578 main.go:76] remote error: rpc error: code = Unknown desc = node doesn't exist +``` + +
Solution: +* Ensure there is networking communication between Target vtctld and Source topology +* Ensure the topology information is correct on the `Mount` command + +--- + +After issuing `Migrate` command everything is stuck at 0% progress +with errors found in target vttablet logs: + +```sh +I0223 20:13:36.825110 1 tablet_picker.go:146] No tablet found for streaming +``` + +
Solution: +* 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`: + + Migrate -- --all --tablet_types "MASTER,REPLICA,RDONLY" ... + +--- + +The MySQL client fails with: + +```sh +SQL error, errno = 1105, state = 'HY000': table 'table_name' does not have a primary vindex +``` + +
Solution: + +* The write was sent to the Target Vitess cluster before the migration completed, + solvable by writing to the source instead, or by completing the migration. diff --git a/content/en/docs/19.0/reference/vreplication/mount.md b/content/en/docs/19.0/reference/vreplication/mount.md new file mode 100644 index 000000000..86426aaf5 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/mount.md @@ -0,0 +1,49 @@ +--- +title: Mount +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. + +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. +{{< /info >}} + + +### 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. diff --git a/content/en/docs/19.0/reference/vreplication/movetables.md b/content/en/docs/19.0/reference/vreplication/movetables.md new file mode 100644 index 000000000..865e73ed0 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/movetables.md @@ -0,0 +1,461 @@ +--- +title: MoveTables +description: Move tables between keyspaces without downtime +weight: 10 +aliases: ['/docs/reference/vreplication/v2/movetables/'] +--- + +{{< warning >}} +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 + +``` +MoveTables -- +``` +or + +``` +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] + +``` + +## Description + +`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` 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. + +## Parameters + +### 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`. + +#### Create +
+ +`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.) + +
+ +#### Progress +
+ +`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 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`. + +
+ +#### 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. + +
+ +#### 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)). + +
+ +#### Complete +
+ +{{< warning >}} +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)). + +
+ +### 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. + +#### --all + +**optional** cannot specify `table_specs` if `--all` is specified +
+ +Move all tables from the source keyspace. + +
+ +#### --auto_start +**optional**\ +**default** true + +
+ +Normally the workflow starts immediately after it is created. If this flag is set +to false then the workflow is in a Stopped state until you explicitly start it. + +
+ +###### Uses + +* Allows updating the rows in `_vt.vreplication` after `MoveTables` has setup the +streams. For example, you can add some filters to specific tables or change the +projection clause to modify the values on the target. This +provides an easier way to create simpler Materialize workflows by first using +`MoveTables` with auto_start false, updating the BinlogSource as required by your +`Materialize` and then start the workflow. +* Changing the `copy_state` and/or `pos` values to restart a broken `MoveTables` workflow +from a specific point of time + +#### --cells +**optional**\ +**default** local cell (of source tablet)\ +**string** + +
+ +Comma seperated list of Cell(s) and/or CellAlias(es) to replicate from. + +
+ +###### Uses + +* Improve performance by picking a tablet in cells in network proximity with the target +* Reduce bandwidth costs by skipping cells that are in different availability zones +* Select cells where replica lags are lower + +#### --defer-secondary-keys +**optional**\ +**default** false + +
+ +If true, any secondary keys are dropped from the table definitions on the target shard(s) as we first initialize the +tables for the [copy phase](../internal/life-of-a-stream/#copy). The exact same key definitions +are then re-added when the copy phase completes for each table. + +With this method all secondary index records for the table are generated in one bulk operation. This should significantly +improve the overall copy phase execution time on large tables with many secondary keys — especially with +[MySQL 8.0.31](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-31.html) and later due to InnoDB's support for +parallel index builds. This is logically similar to the +[`mysqldump` `--disable-keys` option](https://dev.mysql.com/doc/refman/en/mysqldump.html#option_mysqldump_disable-keys). + +
+ +#### --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 + +
+ +If specified, when switching write (primary tablet) traffic for tables that are being moved from an unsharded keyspace to a +sharded one, initialize any sequences being used by those tables on the target. They are initialized using the current +maximum value for the column across all shards on the target. + +
+ +###### Uses + +* It's common that users import unsharded data into Vitess — sharding it in the process — or move +tables from an unsharded keyspace to a sharded one as they become too large for a single MySQL instance. +When doing either of these you would typically be leveraging [MySQL auto_increment](https://dev.mysql.com/doc/refman/en/example-auto-increment.html) +columns for primary keys on the unsharded tables (source). On the sharded target, however, you will then +need to use [Vitess Sequences](../../features/vitess-sequences/) in order to ensure that you continue having +automatically generated incrementing unique primary keys _across all shards_. When it comes to [switching the write traffic](#switchtraffic) +during this move you would need to manually ensure that you [initialize the sequences](../../features/vitess-sequences/#initializing-a-sequence) +so that the next values they provide are higher than any already used on the source (with ample buffer in between +to avoid potential identifier reuse and duplicate key errors immediately following the cutover). This flag tells Vitess +to manage this sequence initialization for you as part of the `SwitchTraffic` operation to ensure a seamless cutover +without any additional manual steps. For more information, please see [the feature request](https://github.com/vitessio/vitess/issues/13685). + +{{< info >}} +You will still need to take the manual step of [creating each backing sequence table](../../features/vitess-sequences/#creating-a-sequence) +in an unsharded keyspace of your choosing prior to the `SwitchTraffic` operation. +{{< /info>}} + +#### --keep_data +**optional**\ +**default** false + +
+ +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` + +
+ +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 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. + +
+ +#### --on-ddl +**optional**\ +**default** IGNORE + +
+ +This flag allows you to specify what to do with DDL SQL statements when they are encountered +in the replication stream from the source. The values can be as follows: + +* `IGNORE`: Ignore all DDLs (this is also the default, if a value for `on-ddl` + is not provided). +* `STOP`: Stop when DDL is encountered. This allows you to make any necessary + changes to the target. Once changes are made, updating the workflow state to + `Running` will cause VReplication to continue from just after the point where + it encountered the DDL. Alternatively you may want to `Cancel` the workflow + and create a new one to fully resync with the source. +* `EXEC`: Apply the DDL, but stop if an error is encountered while applying it. +* `EXEC_IGNORE`: Apply the DDL, but ignore any errors and continue replicating. + +{{< warning >}} +We caution against against using `EXEC` or `EXEC_IGNORE` for the following reasons: + * You may want a different schema on the target + * You may want to apply the DDL in a different way on the target + * The DDL may take a long time to apply on the target and may disrupt replication, performance, and query execution while it is being applied (if serving traffic from the target) +{{< /warning >}} + +
+ +#### --no-routing-rules +**optional**\ +**default** false + +
+Do not create routing rules for the tables being moved when the workflow is created. This implies that you should +not use global routing or send traffic to the target keyspace through a vtgate. +See https://github.com/vitessio/vitess/pull/13895 and https://github.com/vitessio/vitess/issues/13851 for a use-case +and more details. +
+ +#### --rename_tables +**optional**\ +**default** false + +
+ +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. + +
+ +#### --reverse_replication +**optional**\ +**default** true + +
+ +`SwitchTraffic` for primary tablet types, by default, starts a reverse replication stream with the current target as the source, replicating back to the original source. This enables a quick and simple rollback mechanism using `ReverseTraffic`. This reverse workflow name is that of the original workflow concatenated with \_reverse. + +If set to false these reverse replication streams will not be created and you will not be able to rollback once you have switched write traffic over to the target. + +
+ +#### --source +**mandatory** +
+ +Name of existing keyspace that contains the tables to be moved. + +
+ +#### --source_time_zone +**optional**\ +**default** "" + +
+ +Specifying this flag causes all `DATETIME` fields to be converted from the given time zone into `UTC`. It is expected that the application has +stored *all* `DATETIME` fields, in all tables being moved, in the specified time zone. On the target these `DATETIME` values will be stored in `UTC`. + +As a best practice, Vitess expects users to run their MySQL servers in `UTC`. So we do not specify a target time zone for the conversion. +It is expected that the [time zone tables have been pre-populated](https://dev.mysql.com/doc/refman/en/time-zone-support.html#time-zone-installation) on the target mysql servers. + +Any reverse replication streams running after a SwitchWrites will do the reverse date conversion on the source. + +Note that selecting the `DATETIME` columns from the target will now give the times in UTC. It is expected that the application will +perform any conversions using, for example, `SET GLOBAL time_zone = 'US/Pacific'`or `convert_tz()`. + +Also note that only columns of `DATETIME` data types are converted. If you store `DATETIME` values as `VARCHAR` or `VARBINARY` strings, +setting this flag will not convert them. + +
+ +#### --stop_after_copy + +**optional** +**default** false + +
+ +If set, the workflow will stop once the Copy phase has been completed i.e. once +all tables have been copied and VReplication decides that the lag +is small enough to start replicating, the workflow state will be set to Stopped. + +
+ +###### Uses +* 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 +**optional**\ +**default** `--vreplication_tablet_type` parameter value for the tablet. `--vreplication_tablet_type` has the default value of "in_order:REPLICA,PRIMARY".\ +**string** + +
+ +Source tablet types to replicate from (e.g. PRIMARY, REPLICA, RDONLY). The value +specified impacts [tablet selection](../tablet_selection/) for the workflow. + +
+ +#### --timeout +**optional**\ +**default** 30s + +
+ +For primary tablets, SwitchTraffic first stops writes on the source primary and waits for the replication to the target to +catchup with the point where the writes were stopped. If the wait time is longer than timeout +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 `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/) diff --git a/content/en/docs/19.0/reference/vreplication/reshard.md b/content/en/docs/19.0/reference/vreplication/reshard.md new file mode 100644 index 000000000..0aa963eb5 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/reshard.md @@ -0,0 +1,347 @@ +--- +title: Reshard +description: Reshard a keyspace to achieve horizontal scaling +weight: 20 +aliases: ['/docs/reference/vreplication/v2/reshard/'] +--- + +{{< warning >}} +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 -- +``` + +or + +``` +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] +``` + +## Description + +`Reshard` is used to create and manage workflows to horizontally shard an existing keyspace. The source keyspace can be unsharded or sharded. + + +## Parameters + +### 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`. + +#### Create +
+ +`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.) + +
+ +#### Progress +
+ +`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 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`. + +
+ +#### 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. + +
+ +#### 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)). + +
+ +#### Complete +
+ +{{< warning >}} +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)) . + +
+ +### 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. + +#### --auto_start +**optional**\ +**default** true + +
+ +Normally the workflow starts immediately after it is created. If this flag is set +to false then the workflow is in a Stopped state until you explicitly start it. + +
+ +###### Uses + +* Allows updating the rows in `_vt.vreplication` after `Reshard` has setup the +streams. For example, you can add some filters to specific tables or change the +projection clause to modify the values on the target. This +provides an easier way to create simpler Materialize workflows by first using +`Reshard` with auto_start false, updating the BinlogSource as required by your +Materialize and then start the workflow. +* Changing the `copy_state` and/or `pos` values to restart a broken `Reshard` workflow +from a specific point of time + +#### --cells +**optional**\ +**default** local cell (of source tablet)\ +**string** + +
+ +Comma seperated list of Cell(s) and/or CellAlias(es) to replicate from. + +
+ +###### Uses + +* Improve performance by picking a tablet in cells in network proximity with the target +* Reduce bandwidth costs by skipping cells that are in different availability zones +* Select cells where replica lags are lower + +#### --defer-secondary-keys +**optional**\ +**default** false + +{{< warning >}} +This flag is currently **experimental**. +{{< /warning >}} + +
+ +If true, any secondary keys are dropped from the table definitions on the target shard(s) as we first initialize the +tables for the [copy phase](../internal/life-of-a-stream/#copy). The exact same key definitions +are then re-added when the copy phase completes for each table. + +With this method all secondary index records for the table are generated in one bulk operation. This should significantly +improve the overall copy phase execution time on large tables with many secondary keys — especially with +[MySQL 8.0.31](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/news-8-0-31.html) and later due to InnoDB's support for +parallel index builds. This is logically similar to the +[`mysqldump` `--disable-keys` option](https://dev.mysql.com/doc/refman/en/mysqldump.html#option_mysqldump_disable-keys). + +
+ +#### --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. + +
+ +#### --keep_data +**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` + +
+ +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 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. + +
+ +#### --on-ddl +**optional**\ +**default** IGNORE + +
+ +This flag allows you to specify what to do with DDL SQL statements when they are encountered +in the replication stream from the source. The values can be as follows: + +* `IGNORE`: Ignore all DDLs (this is also the default, if a value for `on-ddl` + is not provided). +* `STOP`: Stop when DDL is encountered. This allows you to make any necessary + changes to the target. Once changes are made, updating the workflow state to + `Running` will cause VReplication to continue from just after the point where + it encountered the DDL. Alternatively you may want to `Cancel` the workflow + and create a new one to fully resync with the source. +* `EXEC`: Apply the DDL, but stop if an error is encountered while applying it. +* `EXEC_IGNORE`: Apply the DDL, but ignore any errors and continue replicating. + +{{< warning >}} +We caution against against using `EXEC` or `EXEC_IGNORE` for the following reasons: + * You may want a different schema on the target + * You may want to apply the DDL in a different way on the target + * The DDL may take a long time to apply on the target and may disrupt replication, performance, and query execution while it is being applied (if serving traffic from the target) +{{< /warning >}} + +
+ +#### --reverse_replication +**optional**\ +**default** true + +
+ +`SwitchTraffic` for primary tablet types, by default, starts a reverse replication stream with the current target as the source, replicating back to the original source. This enables a quick and simple rollback mechanism using `ReverseTraffic`. This reverse workflow name is that of the original workflow concatenated with \_reverse. + +If set to false these reverse replication streams will not be created and you will not be able to rollback once you have switched write traffic over to the target. + +
+ +#### --stop_after_copy + +**optional** +**default** false + +
+ +If set, the workflow will stop once the Copy phase has been completed i.e. once +all tables have been copied and VReplication decides that the lag +is small enough to start replicating, the workflow state will be set to Stopped. + +
+ +###### Uses +* 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 +**mandatory** + +
+ +Comma separated shard names to reshard from. + +
+ +#### --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** + +
+ +Source tablet types to replicate from (e.g. PRIMARY, REPLICA, RDONLY). The value +specified impacts [tablet selection](../tablet_selection/) for the workflow. + +
+ +#### --target_shards +**mandatory** + +
+ +Comma separated shard names to reshard to. + +
+ +#### --timeout +**optional**\ +**default** 30s + +
+ +For primary tablets, SwitchTraffic first stops writes on the source primary and waits for the replication to the target to +catchup with the point where the writes were stopped. If the wait time is longer than timeout +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 new file mode 100644 index 000000000..43ee5f173 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/shardlevelmigrations.md @@ -0,0 +1,88 @@ +--- +title: Shard Level Migrations +description: Migrate large keyspaces without downtime +weight: 120 +aliases: ['/docs/reference/vreplication/v2/shardlevelmigrations/'] +--- + +{{< 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 +sure to understand the limitations and requirements below. +{{< /warning >}} + +The full set of options for the `MoveTables` command [can be found here](../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. + +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 +but critical use-case where a large production Vitess setup (100s of shards) is +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 +migration period — *including when shard targeting is used*. + +## Command + +``` +MoveTables --source_shards= +``` + +## Parameters + +#### --source_shards +**mandatory** (for shard level migrations) +
+ +A list of one or more shards that you want to migrate from the source keyspace +to the target keyspace. + +
+ +## Limitations and Requirements + + - 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/) +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 + 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 + - 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 +[`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 +migration is complete. +{{< /warning >}} + +## Related Commands + +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/) +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 new file mode 100644 index 000000000..3af152649 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/tablet_selection.md @@ -0,0 +1,49 @@ +--- +title: Tablet Selection +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. + +{{< 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 +need to replicate the streamed writes within the target shard. +{{< /info >}} + +### Cells and Cell Preference + +By default the `TabletPicker` will only look for viable (healthy and serving) source tablets of the specified tablet type(s) within the local cell (or cell alias within which the local cell belongs) of the +calling process — the `vtgate` managing the VStream or the target `vttablet` for the VReplication stream — and it will select a random one from the candidate +list. If you want to support cross-cell streams then you will need to specify the list of cells or any +[CellAlias](../../programs/vtctl/cell-aliases/) that contain a list of cells using the `--cells` flag in your VReplication +workflow commands like [`MoveTables`](../movetables/) or the +[`VStreamFlags.Cells`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags) field in a +[`VStreamRequest`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamRequest). + +Even with the `--cells` flag specified, by default, the `TabletPicker` will give preference to a healthy and serving tablet within the local cell of the calling process. If there are multiple candidates in the local cell, it will pick one at random. If no healthy tablets exist in the local cell pool, then it will give preference to tablets within cells belonging to the same cell alias as the local cell. If none exist here, then it moves on to selecting candidates from cells provided using the `--cells` flag in your VReplication workflow commands. + +When using the [VTGate VStream API](../vstream/), you can override this local cell preference by specifying the `CellPreference` field as `onlyspecified` and a list of cells with `Cells` in the [VStreamFlags](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags) request object. This will then only pick tablets from the cells provided. + + +### Tablet Types + +#### VReplication +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. + +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. + +{{< 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. +{{< /info >}} + +#### VStream +For a VStream there is no default tablet type. You must specify an individual tablet type using the +[`VStreamRequest.TabletType`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamRequest) field. \ No newline at end of file diff --git a/content/en/docs/19.0/reference/vreplication/throttling.md b/content/en/docs/19.0/reference/vreplication/throttling.md new file mode 100644 index 000000000..9b352184e --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/throttling.md @@ -0,0 +1,32 @@ +--- +title: Throttling +weight: 300 +--- + +### Introduction + +VReplication moves potentially massive amounts of data from one place to another, whether within the same keyspace and shard or across keyspaces. It copies tables and follows up to apply ongoing changes on those tables by reading the binary logs (aka the changelog). + +This places load on both the source side (where VReplication reads data from) as well as on target side (where VReplication writes data to). + +On the source side, VReplication reads the content of tables. This typically means loading pages from disk contending for disk IO, and "polluting" the MySQL buffer pool. The operation competes with normal production traffic for both IO and memory resources. If the source is a replica, the operation may lead to replication lag. If the source is a primary, this may lead to write contention. + +On the target side, VReplication writes massive amount of data. If the target server is a primary with replicas, then the replicas may incur replication lag. + +To help address the above issues, VReplication uses the [tablet throttler](../../features/tablet-throttler/) mechanism to push back both reads and writes. + +### Target Throttling + +On the target side, VReplication wishes to consult the overall health of the target shard (there can be multiple shards to a VReplication workflow, and here we discuss the single shard at the end of a single VReplication stream). That shard may serve production traffic unrelated to VReplication. VReplication therefore consults the internal equivalent of `/throttler/check` when writing data to the shard's primary. This checks the MySQL replication lag on relevant replicas in the shard. The throttler will delay the VReplication writes of both table-copy and changelog events until the shard's replication lag is under the defined threshold (1s by default). + +### Source Throttling + +On the source side, VReplication only affects the single MySQL server it reads from, and has no impact on the overall shard. VStreamer, the source endpoint of VReplication, consults the equivalent of `/throttler/check-self`, which looks for replication lag on the source host. + +As long as `check-self` fails — meaning that the replication lag is not within the defined threshold (1s by default) — VStreamer will not read table data, nor will it pull events from the changelog. + +### Impact of Throttling + +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. diff --git a/content/en/docs/19.0/reference/vreplication/vdiff.md b/content/en/docs/19.0/reference/vreplication/vdiff.md new file mode 100644 index 000000000..a6baa1abd --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/vdiff.md @@ -0,0 +1,309 @@ +--- +title: VDiff +description: Compare the source and target in a workflow to ensure integrity +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 >}} + +### 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: + +#### 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 [] +``` + +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 +``` + +#### 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 +``` + +Example: + +``` +$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer resume 4c664dc2-eba9-11ec-9ef7-920702940ee0 +VDiff 4c664dc2-eba9-11ec-9ef7-920702940ee0 resumed on target shards, use show to view progress +``` + +{{< warning >}} +We cannot guarantee accurate results for `resume` when different collations are used for a table between the source and target keyspaces (more details can be seen [here](https://github.com/vitessio/vitess/pull/10497)). +{{< /warning >}} + +#### Show Progress/Status of a VDiff + +``` +VDiff -- show { | last | all} +``` + +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 + +VDiff Summary for customer.commerce2customer (4c664dc2-eba9-11ec-9ef7-920702940ee0) +State: completed +RowsCompared: 196 +HasMismatch: false +StartedAt: 2022-06-26 22:44:29 +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 +{ + "Workflow": "commerce2customer", + "Keyspace": "customer", + "State": "completed", + "UUID": "4c664dc2-eba9-11ec-9ef7-920702940ee0", + "RowsCompared": 196, + "HasMismatch": false, + "Shards": "0", + "StartedAt": "2022-06-26 22:44:29", + "CompletedAt": "2022-06-26 22:44:31" +} + +$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.p1c2 show daf1f03a-03ed-11ed-9ab8-920702940ee0 +{ + "Workflow": "p1c2", + "Keyspace": "customer", + "State": "started", + "UUID": "daf1f03a-03ed-11ed-9ab8-920702940ee0", + "RowsCompared": 51, + "HasMismatch": false, + "Shards": "-80,80-", + "StartedAt": "2022-07-15 03:26:03", + "Progress": { + "Percentage": 48.57, + "ETA": "2022-07-15 03:26:10" + } +} +``` + +`show all` lists all VDiffs created for the specified keyspace and workflow. + +{{< info >}} +It is too expensive to get exact real-time row counts for tables, using e.g. `SELECT COUNT(*)`. +So we instead use the statistics available in the +[`information_schema`](https://dev.mysql.com/doc/refman/en/information-schema-tables-table.html) +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. +{{< /info >}} + +#### Stopping a VDiff + +``` +VDiff -- stop +``` + +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 +{ + "UUID": "ad9bd40e-0c92-11ed-b568-920702940ee0", + "Action": "stop", + "Status": "completed" +} +``` + +{{< info >}} +Attempting to `stop` a VDiff that is already completed is a no-op. +{{< /info >}} + +#### Delete VDiff Results + +``` +VDiff -- delete { | all} +``` + +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 + +$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2customer delete all +{ + "Action": "delete", + "Status": "completed" +} +``` + +{{< info >}} +Deletes are idempotent, so attempting to `delete` VDiff data that does not exist is a no-op. + +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 new file mode 100644 index 000000000..a18843d0b --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/vdiffv1.md @@ -0,0 +1,166 @@ +--- +title: VDiff v1 +description: Compare the source and target in a workflow to ensure integrity +weight: 40 +--- + +{{< info >}} +This is the legacy v1 VDiff. [VDiff v2](../vdiff/), which runs on tablets, is now production-ready. We recommend that you begin using v2 instead. +{{< /info >}} + +### 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 new file mode 100644 index 000000000..d127d20c2 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/vreplication.md @@ -0,0 +1,209 @@ +--- +title: Overview +description: VReplication features, design and options in a nutshell +weight: 2 +aliases: ['/docs/reference/features/vreplication/'] +--- + +VReplication is a core component of Vitess that can be used to compose +many features. It can be used for the following use cases: + +* **Data Migrations**: Use [`MoveTables`](../movetables/) to migrate tables into + Vitess or across [`Keyspaces`](../../../concepts/keyspace/) with online revertable workflows. +* **Resharding**: Use [`Reshard`](../reshard/) to scale [`Keyspaces`](../../../concepts/keyspace/) + up or down as needed with automated online revertable workflows. +* **Materialized Views**: Use [`Materialize`](../materialize/) to create + a view of the source table in a target keyspace. This materialization + can use a different primary [`vindex`](../../features/vindexes/) than the source. + It can also materialize a subset of the source columns, or add new expressions from + the source. This view will be kept up-to-date in real time. One can also materialize + reference tables onto all shards for improved data locality, allowing + Vitess to perform efficient local joins with those materialized tables. +* **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 + 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. +* **Change Notifications (CDC)**: The [`VStream`](../../../concepts/vstream/) + component of VReplication can be used for the application or a systems + operator to subscribe to change notifications and use it to keep downstream + systems up-to-date with the source. +* **Job Queues**: VReplication can also be used to provide a job queue for + asynchronous processing of data using the [Messaging](../../features/messaging/) + feature. + +## Feature Description + +VReplication works as [a stream or set of streams](../internal/life-of-a-stream/). +Each stream establishes replication from a source keyspace/shard to a +target keyspace/shard. + +A given stream can replicate multiple tables. For each table, you can +specify a `SELECT` statement that represents both the transformation +rule and the filtering rule. The `SELECT` expressions specify the +transformation, and the `WHERE` clause specifies the filtering. + +The `SELECT` expressions can be any non-aggregate MySQL expression, or +they can also be `COUNT` or `SUM` as aggregate expressions. Aggregate +expressions combined with the corresponding `GROUP BY` clauses will +allow you to materialize real-time rollups of the source table, which +can be used for analytics. The target table can have a different name +from the source. + +For a sharded system like Vitess, multiple VReplication streams +may be needed to achieve the objective. This is because there +can be multiple source shards and multiple destination shards, and +the relationship between them may not be one to one. + +VReplication performs the following essential functions: + +* [Copy data](../internal/life-of-a-stream/#copy) + from the source to the destination table in a consistent + fashion. For a large table, this copy can be long-running. It can be + interrupted and resumed. If interrupted, VReplication can keep + the copied portion up-to-date with respect to the source, and it can + resume the copy process at a point that is consistent with the + current replication position. +* After copying is finished, it can continuously [replicate](../internal/life-of-a-stream/#replicate) + the data from the source to destination. +* The copying rule can be expressed as a `SELECT` statement. The + statement should be simple enough that the materialized table can + be kept up-to-date from the data coming from the binlog. For + example, joins in the `SELECT` statement are not supported today. +* Correctness verification: VReplication supports the [VDiff](../vdiff) command + which verifies that the target table is an exact representation of + the `SELECT` statement from the source by capturing consistent + snapshots of the source and target and comparing them against each + other. +* Journaling: If there is any kind of traffic cut-over where we + start writing to a different table than we used + to before, VReplication will save the current binlog positions + into a journal table. This can be used by other streams to resume + replication from the new source. +* Routing rules: Although this feature is itself not a direct + functionality of VReplication, it works hand in hand with it. It + automatically manages sophisticated rules about where to route queries + depending on the type of workflow being performed. For example, + it is used to control the cut-over during [`MoveTables`](../movetables/). + + + +## Other Properties of VReplication + +### Fast Replay + +VReplication has the capability to batch transactions if the send rate of the source +exceeds the replay rate of the destination. This allows it to catch up very quickly +when there is a backlog. Load tests have shown a 3-20X improvement over traditional +MySQL replication depending on the workload. + +### Accurate Lag Tracking + +The source [`VTTablet`](../../../concepts/vtgate/) sends its current time along with every event. This allows the +target to correct for clock skew while estimating replication lag. Additionally, +the source starts sending heartbeats if there is nothing to send. If the target +receives no events from the source at all, it knows that it's definitely lagged +and starts reporting itself accordingly. + +### Self-Replication + +VReplication allows you to set the source keyspace/shard to be the same as the target. +This is especially useful for performing schema rollouts: you can create the target +table with the intended schema and vreplicate from the source table to the new +target. Once caught up, you can cutover to write to the target table. +In this situation, an apply on +the target generates a binlog event that will be picked up by the source and +sent to the target. Typically, it will be an empty transaction. In such cases, +the target does not generally apply these transactions, because such an application +will generate yet another event. However, there are situations where one needs +to apply empty transactions, especially if it's a required stopping point. +VReplication can differentiate between these situations and apply events +only as needed. + +### Deadlocks and Lock Wait Timeouts + +It is possible that multiple streams can conflict with each other and cause +deadlocks or lock waits. When such things happen, VReplication silently retries +such transactions without reporting an error. It does increment a counter so +that the frequency of such occurrences can be tracked. + +### Automatic Retries + +If any other error is encountered, the replication is retried after a short wait. +Each time, the stream searches from the full list of available sources and picks +one at random. + +### Handle DDL + +The [`MoveTables`](../movetables/) and [`Reshard`](../reshard/) commands allow you to +specify a value for `on-ddl`. This allows you to specify what to do with DDL SQL + statements when they are encountered +in the replication stream from the source. The values can be as follows: + +* `IGNORE`: Ignore all DDLs (this is also the default, if a value for `on-ddl` + is not provided). +* `STOP`: Stop when DDL is encountered. This allows you to make any necessary + changes to the target. Once changes are made, updating the state to `Running` + will cause VReplication to continue from just after the point where it + encountered the DDL. +* `EXEC`: Apply the DDL, but stop if an error is encountered while applying it. +* `EXEC_IGNORE`: Apply the DDL, but ignore any errors and continue replicating. + +{{< warning >}} +We caution against against using `EXEC` or `EXEC_IGNORE` for the following reasons: + * You may want a different schema on the target + * You may want to apply the DDL in a different way on the target + * The DDL may take a long time to apply on the target and may disrupt replication, performance, and query execution while it is being applied (if serving traffic from the target) +{{< /warning >}} + +### Failover Continuation + +If a failover is performed on the target keyspace/shard, the new primary will +automatically resume VReplication from where the previous primary left off. + +### Tablet Selection + +VReplication automatically chooses viable tablets for the source and target of a given stream. See [tablet selection](../../vreplication/tablet_selection). + +### Throttling + +VReplication throttles operations when the source or target appear to be overloaded, indicated by replication lag. See [throttling](../../vreplication/throttling). + +## Monitoring and Troubleshooting + +### VTAdmin + +VTAdmin provides views into the current workflows running within a Vitess cluster. +See [`VTAdmin`](../../vtadmin). + +### VTTablet /debug/status + +The first place to look at is the `/debug/status` page of the target primary +[`VTtablet`](../../../concepts/tablet/). The bottom of the page shows the status +of all the VReplication streams. + +Typically, if there is a problem, the `Last Message` column will display the +error. Sometimes, it's possible that the stream cannot find a source. If so, +the `Source Tablet` would be empty. + +### VTTablet Logfile + +If the errors are not clear or if they keep disappearing, the VTTablet's INFO logfile +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. + +### Monitoring Variables + +VReplication also reports [a set of metrics](../metrics/) that can be scraped by +monitoring tools like [Prometheus](https://prometheus.io). + +Thresholds and alerts can be set to draw attention to potential problems. diff --git a/content/en/docs/19.0/reference/vreplication/vreplicationexec.md b/content/en/docs/19.0/reference/vreplication/vreplicationexec.md new file mode 100644 index 000000000..577b645c1 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/vreplicationexec.md @@ -0,0 +1,49 @@ +--- +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/vstream.md b/content/en/docs/19.0/reference/vreplication/vstream.md new file mode 100644 index 000000000..2173cb3e7 --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/vstream.md @@ -0,0 +1,311 @@ +--- +title: VStream +description: Change event streams +weight: 75 +aliases: ['/docs/design-docs/vreplication/vstream/vscopy/'] +--- + +[Vitess Gateways](../../../concepts/vtgate/) (`vtgate`) provide a [`VStream` service](../../../concepts/vstream/) +that allows clients to subscribe to a change event stream for a set of tables. + +## Use Cases + + * **Change Data Capture (CDC)**: `VStream` can be used to capture changes to a + table and send them to a downstream system. This is useful for building + real-time data pipelines. + +## Overview + +`VStream` supports copying the current contents of a table — as you will often not +have the binary logs going back to the creation of the table — and then begin streaming +new changes to the table from that point on. It also supports resuming this initial copy +phase if it's interrupted for any reason. + +Events in the stream are [MySQL row based binary log events](https://dev.mysql.com/doc/refman/en/mysqlbinlog-row-events.html) — with [extended metadata](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VEvent) +— and can be processed by event bridges which support Vitess such as +[Debezium](https://debezium.io/documentation/reference/stable/connectors/vitess.html). +Other products such as [AirByte](https://airbyte.com) can also be used with [custom +Vitess connectors](https://docs.airbyte.com/connector-development/). + +{{< warning >}} +We recommend Debezium as it has native Vitess support and has been used in production +environments by many Vitess users. +{{< /warning >}} + +## API Details + +[`VStream` is a gRPC](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate/vtgateconn#VTGateConn.VStream) +that is part of the [`vtgate`](../../../concepts/vtgate/) service and is accessible via a +[`vtgate`](../../../concepts/vtgate/) process's `--grpc_port`. + +### RPC Parameters + +#### Context + +**Type** [Context](https://pkg.go.dev/context#Context)\ +**Required**\ +**Default** none + +In addition to the typical `Context` usage, it can contain a custom key-value pair where the key is `1` and the value is a +[`CallerID`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtrpc#CallerID). This value is then passed along to +[tablets](../../../concepts/tablet/) to identify the originating client for the request. It is not meant to be secure, but +primarily informational. The client can provide whatever info they want in the +[`CallerID`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtrpc#CallerID) fields and they will be trusted by the servers +as this information is primarily used to aid in monitoring and debugging. The [`vtgate`](../../../concepts/vtgate/) propagates +the value to the source [`vttablet`](../../../concepts/tablet/) processes and the tablets may use this information for various +monitoring, metrics, and logging purposes. It can, however, also be used for other purposes such as denying the client +access to tables during a migration ([`MoveTables`](../movetables/) or [`Reshard`](../reshard/)). + +#### TabletType + +**Type** [TabletType](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/topodata#TabletType)\ +**Required**\ +**Default** UNKNOWN (you must specify a valid type) + +The tablet type to use [when selecting stream source tablets](../tablet_selection/). + +#### VGtid + +**Type** [VGtid](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VGtid)\ +**Required** + +The keyspace, shard, and GTID position list to start streaming from. If no `ShardGtid.Gtid` value is provided +then a [table copy phase](https://github.com/vitessio/vitess/issues/6277) will be initiated for the tables matched +by the provided [filter](#filter) on the given shard. + +If the `ShardGtid.Shard` value is omitted, this means that all shards in the keyspace specified in the `ShardGtid.Keyspace` value are included. +Additionally, if the `ShardGtid.Keyspace` value has a `/` prefix, you can use regular expressions such as `/.*` to include all keyspaces. + +#### Filter + +**Type** [Filter](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#Filter)\ +**Required** + +The tables which you want to subscribe to change events from — in the given keyspace(s) and shard(s) contained +in the provided [VGtid](#vgtid) — and any query predicates to use when filtering the rows for which change +events will be generated. + +#### VStreamFlags + +##### MinimizeSkew + +**Type** bool\ +**Default** false + +When enabled the `vtgate` will keep the events in the stream roughly time aligned — it is aggregating streams coming +from each of the shards involved — using the event timestamps to ensure the maximum time skew between the source +tablet shard streams is kept under 10 minutes. When it detects skew between the source streams it will pause sending +the client more events and allow the lagging shard(s) to catch up. + +{{< info >}} +There is no strict ordering of events across shards and the client will need to examine the event timestamps. +{{}} + +##### HeartbeatInterval + +**Type** unsigned integer\ +**Default** 0 (none) + +How frequently, in seconds, to send heartbeat events to the client when there are no other events in the stream to +send. + +##### StopOnReshard + +**Type** bool\ +**Default** false + +When enabled the `vtgate` will send a reshard event to the client along with an `EOF` +`error` in the [`VStreamReader.Recv`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate/vtgateconn#VStreamReader) +response and stop sending any further events. + +##### Cells + +**Type** string\ +**Default** "" + +If specified, these cells (comma-separated list) are used +[when selecting stream source tablets](../tablet_selection/). When no value is specified the `vtgate` will +default to looking for source tablets within its own local cell. + +##### CellPreference + +**Type** string\ +**Default** "" + +If specified, this determines which cells to give preference to during [tablet selection](../tablet_selection/). +By default, `preferlocalwithalias` is used in order to give preference to the caller's local cell and then any alias its cell belongs to. +If `onlyspecified` is given, then only tablets within the specified `Cells` field value will be considered. + +##### TabletOrder + +**Type** string\ +**Default** "" + +This replaces the `in_order` hint (e.g. `"in_order:REPLICA,PRIMARY"`) previously used to specify tablet type order [during source tablet selection](../tablet_selection/). + +### RPC Response + +The [`VStream` gRPC](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate/vtgateconn#VTGateConn.VStream) returns +a [`VStreamReader`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate/vtgateconn#VStreamReader) and a non-nil `error` if +the stream could not be initialized. You would call the `Recv` method on that +[`VStreamReader`](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate/vtgateconn#VStreamReader) in a for loop and +responses will be sent when available. Each response consisting of the following two parameters: + * An array of [`VEvent`](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VEvent) objects — the new messages to process in the stream + * An `error` — an error that, if non-nil, indicates the stream has been closed (`EOF`) or an error occurred + +### API Types + * [TabletType](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/topodata#TabletType) + * [VGtid](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VGtid) + * [ShardGtid](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#ShardGtid) + * [Filter.Rule](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#Rule) + * [LastPKEvent](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#LastPKEvent) + * [TableLastPK](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#TableLastPK) + * [VStreamFlags](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags) + * [VStreamReader](https://pkg.go.dev/vitess.io/vitess/go/vt/vtgate/vtgateconn#VStreamReader) + * [VEvent](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/binlogdata#VEvent) + +### Example Usage + +You can find a full example go client [here](https://github.com/vitessio/vitess/blob/main/examples/local/vstream_client.go). + +Below is a snippet showing how to use the `VStream` API in go: +```go +gconn, err := vtgateconn.Dial(ctx, grpcAddress) +if err != nil { + t.Fatal(err) +} +defer gconn.Close() + +// lastPK is id1=4 +lastPK := sqltypes.Result{ + Fields: []*query.Field{{Name: "id1", Type: query.Type_INT64}}, + Rows: [][]sqltypes.Value{{sqltypes.NewInt64(4)}}, +} +tableLastPK := []*binlogdatapb.TableLastPK{{ + TableName: "t1", + Lastpk: sqltypes.ResultToProto3(&lastPK), +}} + +var shardGtids []*binlogdatapb.ShardGtid +var vgtid = &binlogdatapb.VGtid{} +shardGtids = append(shardGtids, &binlogdatapb.ShardGtid{ + Keyspace: "ks", + Shard: "-80", + Gtid: "MySQL56/89f66ef2-863a-11ed-9bdf-3d270fd3f552:1-30219" + TablePKs: tableLastPK, +}) +shardGtids = append(shardGtids, &binlogdatapb.ShardGtid{ + Keyspace: "ks", + Shard: "80-", + Gtid: "MySQL56/2174b383-5441-11e8-b90a-c80aa9429562:1-29516,24da167-0c0c-11e8-8442-00059a3c7b00:1-19" + TablePKs: tableLastPK, +}) +vgtid.ShardGtids = shardGtids +filter := &binlogdatapb.Filter{ + Rules: []*binlogdatapb.Rule{{ + Match: "t1", + Filter: "select * from t1", + }}, +} +flags := &vtgatepb.VStreamFlags{} +reader, err := gconn.VStream(ctx, topodatapb.TabletType_PRIMARY, vgtid, filter, flags) + +var evs []*binlogdatapb.VEvent +for { + e, err := reader.Recv() + ... +``` + +
+ +#### Copy All Tables From All Shards in the `ks` Keyspace + +Below is a snippet in Go that demonstrates how to copy from all shards by omitting `ShardGtid.Shard`: + +```go +vgtid := &binlogdatapb.VGtid{ + ShardGtids: []*binlogdatapb.ShardGtid{{ + Keyspace: "ks", + Gtid: "", + }}, +} +filter := &binlogdatapb.Filter{ + Rules: []*binlogdatapb.Rule{{ + Match: "/.*", + }}, +} +flags := &vtgatepb.VStreamFlags{} +reader, err := gconn.VStream(ctx, topodatapb.TabletType_PRIMARY, vgtid, filter, flags) +``` + +
+ +#### Copy All Tables From All Shards in All Keyspaces + +Below is a snippet in Go that demonstrates how to copy from all keyspaces by specifying `/.*` as the value for `ShardGtid.Keyspace`: + +```go +vgtid := &binlogdatapb.VGtid{ + ShardGtids: []*binlogdatapb.ShardGtid{{ + Keyspace: "/.*", + Gtid: "", + }}, +} +filter := &binlogdatapb.Filter{ + Rules: []*binlogdatapb.Rule{{ + Match: "/.*", + }}, +} +flags := &vtgatepb.VStreamFlags{} +reader, err := gconn.VStream(ctx, topodatapb.TabletType_PRIMARY, vgtid, filter, flags) +``` + +
+{{< warning >}} +Copying from all keyspaces can generate a significant amount of load and potentially impact production traffic. +Therefore, please exercise caution when using regular expressions in production. +{{< /warning >}} + +## Debugging + +There is also an SQL interface that can be used for testing and debugging from a `vtgate`. Here's an example: +```mysql +$ mysql --quick + +mysql> SET WORKLOAD=OLAP; + +mysql> VSTREAM * FROM commerce.corder\G +*************** 1. row *************** + op: + + order_id: 1 +customer_id: 1 + sku: NULL + price: 10 +************** 2. row *************** + op: * + order_id: 1 +customer_id: 1 + sku: NULL + price: 7 +************** 3. row *************** + op: - + order_id: 1 +customer_id: 1 + sku: NULL + price: 7 +… +``` + +## Monitoring +VTGates publish vstream metrics listed [here](../metrics/#vtgate-metrics). + +## More Reading + + * [VStream Copy](https://github.com/vitessio/vitess/issues/6277) + * [VStream API and Resharding](../internal/vstream-stream-migration/) + * [VStream Skew Minimization](../internal/vstream-skew-detection/) + * Debezium Connector for Vitess + * [Docs](https://debezium.io/documentation/reference/stable/connectors/vitess.html) + * [Source](https://github.com/debezium/debezium-connector-vitess/) + * Blog posts + * [Streaming Vitess at Bolt](https://medium.com/bolt-labs/streaming-vitess-at-bolt-f8ea93211c3f) diff --git a/content/en/docs/19.0/reference/vreplication/workflow.md b/content/en/docs/19.0/reference/vreplication/workflow.md new file mode 100644 index 000000000..7cd2606fc --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/workflow.md @@ -0,0 +1,82 @@ +--- +title: Workflow +description: Wrapper on VReplication to perform common actions on a workflow +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 +``` diff --git a/content/en/docs/19.0/reference/vtadmin/_index.md b/content/en/docs/19.0/reference/vtadmin/_index.md new file mode 100644 index 000000000..1bc9cf787 --- /dev/null +++ b/content/en/docs/19.0/reference/vtadmin/_index.md @@ -0,0 +1,5 @@ +--- +title: VTAdmin +weight: 7 +--- + diff --git a/content/en/docs/19.0/reference/vtadmin/architecture.md b/content/en/docs/19.0/reference/vtadmin/architecture.md new file mode 100644 index 000000000..cf0f00dd1 --- /dev/null +++ b/content/en/docs/19.0/reference/vtadmin/architecture.md @@ -0,0 +1,91 @@ +--- +title: Architecture +--- + +# Overview + +VTAdmin is made up of two components: +- `vtadmin-web`, the browser interface +- `vtadmin-api`, the HTTP(S) and gRPC API + +The `vtadmin-web` front-end queries its data from `vtadmin-api`. In turn, `vtadmin-api` issues queries against the vtgates and vtctlds across one or more Vitess clusters. The [clusters.yaml config file](https://github.com/vitessio/vitess/blob/main/doc/vtadmin/clusters.yaml) defines this mapping from VTAdmin to cluster(s). + +Single-cluster deployments are the simplest and most common configuration. The local example in the ["Get Started" documentation](../../../get-started/) is a good example of a single-cluster deployment. + +```mermaid +flowchart LR + vtadmin-web --> vtadmin-api + vtadmin-api --> vtgate + vtadmin-api --> vtctld + + vtgate <--> topology + vtctld <--> topology + + topology["Topology Service"] +``` + +Large Vitess deployments can be "multi-cluster". These environments have two or more Vitess clusters, each with its own Topology Service, that are isolated from one another. VTAdmin supports these, too. An example of a multi-cluster Vitess deployment is an environment that has one Vitess cluster per geographic region: + +```mermaid +flowchart LR + vtadmin-web --> vtadmin-api + + vtadmin-api --> vtgate_us + vtadmin-api --> vtctld_us + + vtadmin-api --> vtgate_ap + vtadmin-api --> vtctld_ap + + subgraph us-east-1 + topology_us["Topology Service"] + vtgate_us["vtgate"] + vtctld_us["vtctld"] + + vtgate_us <--> topology_us + vtctld_us <--> topology_us + end + + subgraph ap-east-1 + topology_ap["Topology Service"] + vtgate_ap["vtgate"] + vtctld_ap["vtctld"] + + vtgate_ap <--> topology_ap + vtctld_ap <--> topology_ap + end +``` + +# The Life Cycle of a VTAdmin Request + +To understand how data moves through VTAdmin, let's look at life cycle of a typical request: fetching a list of all of the schemas. We'll use the single-cluster ["Get Started"](../../../get-started/) environment as an example: + +A list of schemas in VTAdmin + +When a user loads the `/schemas` view in the browser, `vtadmin-web` makes an HTTP `GET /api/schema/local/commerce/corder` request to `vtadmin-api`. `vtadmin-api` then issues gRPC requests to the vtgates and vtctlds in the cluster to construct the list of schemas. Here's what that looks like in detail: + +```mermaid +sequenceDiagram + autonumber + + participant W as vtadmin-web + participant A as vtadmin-api + participant G as vtgate + participant V as vtctld + + W ->> A: GET /api/schemas + A ->> G: SHOW vitess_tablets + A ->> V: GetKeyspaces + A ->> V: GetSchema + Note left of V: { Keyspace: "commerce", TabletAlias: "zone1-101" } + A ->> V: GetSchema + Note left of V: { Keyspace: "customer", TabletAlias: "zone1-201" } + A ->> W: 200 OK + Note right of W: { "schemas": [...] } +``` + +1. `vtadmin-web` makes a `GET /api/schema/local/commerce/corder` request against `vtadmin-api`'s HTTP endpoint. +2. `vtadmin-api` discovers a vtgate in the cluster and issues a `SHOW vitess_tablets` query on that vtgate to get a list of all tablets in the cluster. +3. `vtadmin-api` discovers a vtctld in the cluster and makes a `GetKeyspaces` gRPC request to get a list of all keyspaces in the cluster. +4. For each of these keyspaces, `vtadmin-api` chooses a random, serving tablet. The keyspace and tablet alias are used to make a `GetSchema` gRPC request to the vtctld to get the full schema, with all of the tables, on that tablet in the keyspace. +5. Since the "Get Started" example has two keyspaces, `commerce` and `customer`, `vtadmin-api` issues separate requests in parallel. +6. Finally, the `GetSchema` gRPC response is annotated with additional metadata (like cluster information), and returned to `vtadmin-web` as JSON. diff --git a/content/en/docs/19.0/reference/vtadmin/cluster_discovery.md b/content/en/docs/19.0/reference/vtadmin/cluster_discovery.md new file mode 100644 index 000000000..1b64198ff --- /dev/null +++ b/content/en/docs/19.0/reference/vtadmin/cluster_discovery.md @@ -0,0 +1,199 @@ +--- +title: Cluster Discovery +--- + +# Overview +VTAdmin manages to be stateless because it mostly proxies queries to VTGates and Vtctlds within Vitess clusters. It is able to do this through **cluster discovery**, the mechanism by which addresses for VTGates and Vtctlds are discovered. + +Discovery is specified as a part of [cluster configuration](https://github.com/vitessio/vitess/blob/main/doc/vtadmin/clusters.yaml). Cluster configuration is passed as the command line argument `--cluster` to VTAdmin API like so: +```bash +vtadmin \ + --addr ":14200" \ + --http-origin "http://localhost:14201" \ + --http-tablet-url-tmpl "http://{{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" \ + --tracer "opentracing-jaeger" \ + --grpc-tracing \ + --http-tracing \ + --logtostderr \ + --alsologtostderr \ + --rbac \ + --rbac-config="./vtadmin/rbac.yaml" \ + --cluster "id=local,name=local,discovery=staticfile,discovery-staticfile-path=./vtadmin/discovery.json,tablet-fqdn-tmpl={{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" +``` +where, in this example, `discovery=staticfile` is specifying static file discovery. + +VTAdmin API currently supports a few methods for discovery: + +#### Static file discovery +With **static file discovery**, VTGate and Vtctld addresses are specified in a static file, whose path is provided as a parameter to the `--cluster` command line argument: +```bash + --cluster "id=local,name=local,discovery=staticfile,discovery-staticfile-path=./vtadmin/discovery.json,tablet-fqdn-tmpl={{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" +``` +
+In this example, the file lives at `./vtadmin/discovery.json`, and might look like: + +```json +{ + "vtctlds": [ + { + "host": { + "fqdn": "localhost:15000", + "hostname": "localhost:15999" + } + } + ], + "vtgates": [ + { + "host": { + "fqdn": "localhost:15001", + "hostname": "localhost:15991" + } + } + ] +} +``` + +where `fqdn` specifies the address of the component's web UI, and `hostname` specifies the address of the component's gRPC server. + +##### Multiple clusters +To specify multiple clusters, repeat the `--cluster` flag: +```bash +vtadmin \ + --addr ":14200" \ + --http-origin "http://localhost:14201" \ + --http-tablet-url-tmpl "http://{{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" \ + --tracer "opentracing-jaeger" \ + --grpc-tracing \ + --http-tracing \ + --logtostderr \ + --alsologtostderr \ + --rbac \ + --rbac-config="./vtadmin/rbac.yaml" \ + --cluster "id=local,name=local,discovery=staticfile,discovery-staticfile-path=./vtadmin/discovery-local.json,tablet-fqdn-tmpl={{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" + --cluster "id=prod,name=prod,discovery=staticfile,discovery-staticfile-path=./vtadmin/discovery-prod.json,tablet-fqdn-tmpl={{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" +``` +
+The above multi-cluster configuration would show up in VTAdmin Web as: + +Multiple clusters on the /clusters page in VTAdmin + +### Dynamic discovery +It is possible to discover clusters _after_ VTAdmin API has been initialized through **dynamic discovery**. When using dynamic discovery, a cluster configuration is passed as either [gRPC metadata](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md) or an HTTP header cookie. + +A very basic cluster configuration may look like: +```json +{ + "id": "dynamic", + "name": "my-dynamic-cluster", + "discovery": "dynamic", + "discovery-dynamic-discovery": "{\"vtctlds\": [ { \"host\": { \"fqdn\": \"localhost:15000\", \"hostname\": \"localhost:15999\" } } ], \"vtgates\": [ { \"host\": {\"hostname\": \"localhost:15991\" } } ] }" +} +``` +
+ +In order to use dynamic discovery, set command line argument `--enable-dynamic-clusters=true`. At this time, it is only possible to discover a single cluster with each request. We're working on adding multicluster support to dynamic discovery. +#### HTTP header cookie +A cluster configuration can be passed as an HTTP cookie named `cluster` along with HTTP requests. + +When passing a cluster configuration as an HTTP header cookie, the cluster configuration must first be base64 encoded and then URL encoded. A cURL request with the above cluster configuration would look like: + +```bash +$ curl -X GET \ + http://localhost:14200/api/clusters \ + -H 'cookie: cluster=ewogICAgImlkIjogImR5bmFtaWMiLAogICAgIm5hbWUiOiAibXktZHluYW1pYy1jbHVzdGVyIiwKICAgICJkaXNjb3ZlcnkiOiAiZHluYW1pYyIsCiAgICAiZGlzY292ZXJ5LWR5bmFtaWMtZGlzY292ZXJ5IjogIntcInZ0Y3RsZHNcIjogWyB7IFwiaG9zdFwiOiB7IFwiZnFkblwiOiBcImxvY2FsaG9zdDoxNTAwMFwiLCBcImhvc3RuYW1lXCI6IFwibG9jYWxob3N0OjE1OTk5XCIgfSB9IF0sIFwidnRnYXRlc1wiOiBbIHsgXCJob3N0XCI6IHtcImhvc3RuYW1lXCI6IFwibG9jYWxob3N0OjE1OTkxXCIgfSB9IF0gfSIKfQ%3D%3D' + +{"result":{"clusters":[{"id":"dynamic","name":"my-dynamic-cluster"}]},"ok":true} +``` +
+ +#### gRPC metadata +A cluster configuration can also be passed as gRPC metadata with the key `cluster`. The code snippet below does the following: +1. Creates a gRPC connection to the VTAdmin client at address `localhost:14200` +2. Creates an outgoing context and adds the cluster configuration as gRPC metadata +3. Calls `GetClusters` with the created context and gRPC metadata + +```golang +package main + +import ( + "context" + "encoding/base64" + "flag" + "fmt" + + "google.golang.org/grpc" + "google.golang.org/grpc/metadata" + + "vitess.io/vitess/go/cmd/vtctldclient/cli" + "vitess.io/vitess/go/vt/log" + + vtadminpb "vitess.io/vitess/go/vt/proto/vtadmin" +) + +func main() { + addr := flag.String("addr", ":14200", "") + + flag.Parse() + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + cc, err := grpc.DialContext(ctx, *addr, grpc.WithInsecure()) + fatal(err) + + defer cc.Close() + + client := vtadminpb.NewVTAdminClient(cc) + clusterJSON := `{ + "id": "dynamic", + "name": "my-dynamic-cluster", + "vtctlds": [ + { + "host": { + "fqdn": "localhost:15000", + "hostname": "localhost:15999" + } + } + ], + "vtgates": [ + { + "host": { + "hostname": "localhost:15991" + } + } + ] + } + ` + + ctx = metadata.NewOutgoingContext(ctx, metadata.New(map[string]string{ + "cluster": base64.StdEncoding.EncodeToString([]byte(clusterJSON)), + })) + + resp, err := client.GetClusters(ctx, &vtadminpb.GetClustersRequest{}) + if err != nil { + log.Fatal(err) + } + + data, err := cli.MarshalJSON(resp) + if err != nil { + log.Fatal(err) + } + + fmt.Printf("%s\n", data) +} +``` +
+ +The result of the above program is: +```bash +$ ./bin/vtadminclient +{ + "clusters": [ + { + "id": "dynamic", + "name": "my-dynamic-cluster" + } + ] +} +``` +A full gist example can be found [here](https://gist.github.com/ajm188/5b5c8ba0cc5660298697e0f762081d45). \ No newline at end of file diff --git a/content/en/docs/19.0/reference/vtadmin/img/schemas.png b/content/en/docs/19.0/reference/vtadmin/img/schemas.png new file mode 100644 index 000000000..59e343e69 Binary files /dev/null and b/content/en/docs/19.0/reference/vtadmin/img/schemas.png differ diff --git a/content/en/docs/19.0/reference/vtadmin/operators_guide.md b/content/en/docs/19.0/reference/vtadmin/operators_guide.md new file mode 100644 index 000000000..e775d2ab9 --- /dev/null +++ b/content/en/docs/19.0/reference/vtadmin/operators_guide.md @@ -0,0 +1,118 @@ +--- +title: Operator's Guide +description: How to configure and run VTAdmin +--- + +{{< info >}} +If you run into issues or have questions, we recommend posting in our [#feat-vtadmin Slack channel](https://vitess.slack.com/archives/C01H307F68J). Click the Slack icon in the top right to join. This is a very active community forum and a great place to interact with other users. +{{< /info >}} + +## Get Started + +This guide describes how to configure and build the VTAdmin API server (`vtadmin`) and front-end (`vtadmin-web`). + +If you intend to use the Vitess operator to deploy VTAdmin please refer to [Running with Vitess Operator](../running_with_vtop). + +The simplest VTAdmin deployment involves a single Vitess cluster. You can look +at the [local example][local_example] for a +minimal invocation of the `vtadmin` and `vtadmin-web` binaries. + +### Prerequisites + +- Building `vtadmin-web` requires [node](https://nodejs.org/en/) at the version given in the [package.json file](https://github.com/vitessio/vitess/blob/main/web/vtadmin/package.json). + +### 1. Define the cluster configuration + +VTAdmin is mapped to one or more Vitess clusters two ways: + +- Add a `clusters.yaml` file and pass its path to `vtadmin` with the `--cluster-config` build flag +- Set the `--cluster` and/or `--cluster-defaults` flags when running `vtadmin`, described in the next section. + +When both command-line cluster configs and a config file are provided, any options for a given cluster on the command-line take precedence over options for that cluster in the config file. + +For a well-commented example enumerating the cluster configuration options, see [clusters.example.yaml](https://github.com/vitessio/vitess/blob/main/doc/vtadmin/clusters.yaml). + + +### 2. Configure `vtadmin` + +Configure the flags for the `vtadmin` process. The full list of flags is given in the [`vtadmin` reference documentation][vtadmin_flag_ref]. + +The following is from the [local example][local_example] showing a minimal set of flags. Here, we define the cluster configuration with the `--cluster` flag and use static (file-based) discovery configured in the [local example's `discovery.json` file][discovery_json]. + +``` +vtadmin \ + --addr ":14200" \ + --http-origin "https://vtadmin.example.com:14201" \ + --http-tablet-url-tmpl "http://{{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" \ + --tracer "opentracing-jaeger" \ + --grpc-tracing \ + --http-tracing \ + --logtostderr \ + --alsologtostderr \ + --no-rbac \ + --cluster "id=local,name=local,discovery=staticfile,discovery-staticfile-path=./vtadmin/discovery.json,tablet-fqdn-tmpl={{ .Tablet.Hostname }}:15{{ .Tablet.Alias.Uid }}" +``` + +To optionally configure role-based access control (RBAC), refer to the [RBAC documentation][rbac_docs]. + +### 3. Configure and build `vtadmin-web` + +Environment variables can be defined in a `.env` file or passed inline to the `npm run build` command. The full list of flags is given in the [`vtadmin-web` reference documentation][vtadmin_web_env_ref]. + +The following is from the [local example][local_example] showing a minimal set of environment variables. `$web_dir`, in this case, refers to the [`vtadmin-web` source directory][vtadmin_web_src] but could equally apply to the `web/vtadmin/` directory copied into a Docker container, for example. `VITE_VTADMIN_API_ADDRESS` uses the same hostname as the `--addr` flag passed to `vtadmin` in the previous step. + +``` +npm --prefix $web_dir --silent install + +VITE_VTADMIN_API_ADDRESS="https://vtadmin-api.example.com:14200" \ + VITE_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS="true" \ + npm run --prefix $web_dir build +``` + +If you want to overwrite or set environment variables after the build you can use the `$web_dir/build/config/config.js` file. +For example: + +```javascript +window.env = { + 'VITE_VTADMIN_API_ADDRESS': "https://vtadmin-api.example.com:14200", + 'VITE_FETCH_CREDENTIALS': "omit", + 'VITE_ENABLE_EXPERIMENTAL_TABLET_DEBUG_VARS': true, + 'VITE_BUGSNAG_API_KEY': "", + 'VITE_DOCUMENT_TITLE': "", + 'VITE_READONLY_MODE': false, +}; +``` + +After running `build` command, the production build of the front-end assets will be in the `$web_dir/build` directory. They can be served as any other static content; for example, [Go's embed package][go_embed] or npm's [serve package][npm_serve]. Each filename inside of `$web_dir/build/assets` will contain a unique hash of the file contents. + +## Best Practices + +Now that you can build and run VTAdmin, there are a few best practices you should follow before deploying into production. +Because VTAdmin by definition has access to potentially-sensitive information about your clusters, it's important to ensure that only the right people have access to those resources. + +### Use Role-based Access Control (RBAC) + +VTAdmin provides RBAC to provide administrators a mechanism for controlling who can perfom what actions across their clusters. +Out of the box, having no RBAC configuration at all will allow anyone to do anything in any cluster, while an empty RBAC configuration will prevent anyone from doing anything in any cluster. + +It is strongly recommended to provide at least some minimal RBAC configuration when deploying VTAdmin. +When designing your particular configuration, it is best to apply the [principle of least privilege][principle_of_least_privilege]. +For example, you should avoid applying a `*` actor to a write action, or a `*` action to resources that are subject to write actions. + +For further reading on VTAdmin's RBAC design, please refer to the [reference page][rbac_docs]. + +### Deploy in a trusted environment + +There is no trust boundary between `vtadmin-web` and `vtadmin-api`, with deployment-specific authentication mechanisms being left to the operator to design for their specific environment. +As such, you should deploy VTAdmin **within** a trusted environment, for example, behind a single sign-on (SSO) integration, such as [okta](https://developer.okta.com/docs/guides/sign-into-web-app-redirect/go/main/). + +[discovery_json]: https://github.com/vitessio/vitess/blob/main/examples/local/vtadmin/discovery.json +[go_embed]:https://pkg.go.dev/embed +[local_example]: https://github.com/vitessio/vitess/blob/main/examples/local/scripts/vtadmin-up.sh +[npm_serve]: https://www.npmjs.com/package/serve +[principle_of_least_privilege]: https://csrc.nist.gov/glossary/term/least_privilege#:~:text=Definition(s)%3A,needs%20to%20perform%20its%20function. +[rbac_docs]: ../role-based-access-control +[vtadmin_flag_ref]: ../../programs/vtadmin +[vtadmin_web_env_ref]: ../../programs/vtadmin-web +[vtadmin_web_src]: https://github.com/vitessio/vitess/tree/main/web/vtadmin +[web_caching]: https://create-react-app.dev/docs/production-build/#static-file-caching diff --git a/content/en/docs/19.0/reference/vtadmin/role-based-access-control.md b/content/en/docs/19.0/reference/vtadmin/role-based-access-control.md new file mode 100644 index 000000000..6ea5ab0a9 --- /dev/null +++ b/content/en/docs/19.0/reference/vtadmin/role-based-access-control.md @@ -0,0 +1,270 @@ +--- +title: Role-Based Access Control +--- + +# Overview + +VTAdmin provides an (optional) role-based access control (RBAC) system for deployments that need to, or would like to, restrict access to specific resources to specific users. + +In VTAdmin, RBAC is governed by two distinct layers: +- **Authentication**: Given a request, determine _who_ is attempting to take an action on a resource +- **Authorization**: Given an actor (obtained from the authentication layer), determine if that actor is allowed to take a certain action on a certain resource. + +Let's discuss each in turn. + +## Authentication + +VTAdmin uses a plugin-based architecture for deployments to provide their own authentication implementation specific to their environment and needs. + +The authentication plugin is installed as both an HTTP middleware and gRPC interceptor, and must implement the following [interface][authn_interface]: + +```go +type Authenticator interface { + // Authenticate returns an Actor given a context. This method is called + // from the stream and unary grpc server interceptors, and are passed the + // stream and request contexts, respectively. + // + // Returning an error from the authenticator will fail the request. To + // denote an authenticated request, return (nil, nil) instead. + Authenticate(ctx context.Context) (*Actor, error) + // AuthenticateHTTP returns an actor given an http.Request. + // + // Returning an error from the authenticator will fail the request. To + // denote an authenticated request, return (nil, nil) instead. + AuthenticateHTTP(r *http.Request) (*Actor, error) +} +``` +
+ +If running with an authentication plugin installed, VTAdmin will invoke its `Authenticate` method on all incoming gRPC requests, and its `AuthenticateHTTP` method on all incoming HTTP requests. + +Returning an error from either of these methods will fail the request with an `UNAUTHENTICATED` code for gRPC requests and an `UNAUTHORIZED` response for HTTP requests. +In order to indicate "no authenticated actor" to the authorization layer, the methods must return `(nil, nil)` instead. + +### Available Plugins + +VTAdmin currently provides no authentication plugins out of the box, though this may change in future releases. + +However, users are free to define their own implementations suited to the needs of their specific deployment and environment. +As an example, [here][example_authn] is an authentication plugin that extracts a "user" key from an HTTP cookie or gRPC incoming metadata. + +### Installing Plugins + +VTAdmin supports two ways of installing an authentication plugin. + +For universal support, users may recompile `vtadmin-api` after adding their authentication plugin file within `go/vt/vtadmin/rbac/plugin_.go`. +If following this process, you must ensure to call `RegisterAuthenticator("your_authn_name", yourAuthnConstructor())` in an `init` function. +This is the pattern followed by other components of Vitess; [tracing plugins][jaeger_plugin_example] are one of many you can refer to. + +If you plan to run `vtadmin-api` on Linux, FreeBSD, or macOS, you can also install your authentication plugin using the [Go plugin API][go_plugin_pkg_docs]. +If following this process, your Authenticator must be built with `go build -buildmode=plugin`, and its `main` package must expose a function of the following name and type: + +```go +package main + +import "vitess.io/vitess/go/vt/vtadmin/rbac" + +func NewAuthenticator() rbac.Authenticator { return ... /* your implementation here */ } +``` + +### Configuration + +Finally, to instruct VTAdmin to use your Authenticator, specify its name in the `"authenticator"` key in your `rbac.yaml`: + +```yaml +authenticator: "./path/to/your_authn_name.so" # or just "your_authn_name" (see below) +``` +
+ +If the name ends in `.so`, VTAdmin will assume it is a Go plugin (the second option described in the previous section). +VTAdmin will attempt to open the plugin and find a function named `NewAuthenticator` that returns an `rbac.Authenticator` implementation. +If any of this fails, VTAdmin will refuse to start; attempting to use this option on platforms not supported by the Go plugin API will result in undefined behavior. + +Otherwise, VTAdmin will assume it was (re-)compiled with a `plugin_.go` file that invoked `RegisterAuthenticator` with that name. +If there is no plugin registered with that name, VTAdmin will refuse to start. + +## Authorization + +Unlike authentication, which occurs at the incoming request boundary (both HTTP and gRPC), authorization happens within the `vtadmin.API` layer itself. + +In each method, the API extracts any `Actor` from the authentication layer, and performs one or more checks to see if that actor is allowed to perform the actions necessary to fulfill the request. +We'll go over how this works in more detail, but as an example, here's a snippet of the `GetClusters` handler: + +```go +func (api *API) GetClusters(ctx context.Context, req *vtadminpb.GetClustersRequest) (*vtadminpb.GetClustersResponse, error) { + clusters, _ := api.getClustersForRequest(nil) // `nil` implies "all clusters" + resp := &vtadminpb.GetClustersResponse{ + Clusters: make([]*vtadminpb.Cluster, 0, len(clusters)), + } + + for _, c := range clusters { + if !api.authz.IsAuthorized(ctx, c.ID, rbac.ClusterResource, rbac.GetAction) { + continue + } + + resp.Clusters = append(resp.Clusters, &vtadminpb.Cluster{ + Id: c.ID, + Name: c.Name, + }) + } + + return resp, nil +} +``` +
+ +First, it's necessary to note that there's a shim layer in the HTTP/gRPC middlewares that puts any `Actor` from an authentication plugin into the `ctx` that gets passed to the method you see here. +The details of how this works are not particularly relevant to this documentation, but you can refer to [these][http_authn_handler] [files][grpc_authn_interceptors] if you would like to learn more. + +Second, it is possible to run VTAdmin with authorization but without an authentication plugin installed. +If you do this, all requests will implicitly be made by the "unauthenticated" actor, and therefore may only access resources that permit the wildcard `Subject` (more on RBAC configs in a bit!). + +Third, and most important: note that being unauthorized to access to a `(cluster, resource, action)` **does not fail the overall request**. +If a request involves multiple clusters, and the actor is permitted to access a subset of them, the request will proceed for those clusters. +If a user tries to access a cluster they are not permitted to, **including a cluster that does not exist**, they will be unable to tell if +(1) there is simply no data; (2) they do not have access to the cluster; or (3) the cluster exists at all. +This is by design, to prevent a malicious actor from being able to enumerate resources by brute force and interpreting the authorization failure responses. + +### Configuration + +Authorization rules are specified as a list under the `rules` key of your `rbac.yaml` configuration file. +Each rule is a 4-key map, corresponding to the 4-tuple of `(resource, cluster, subject, action)`. + +In order to allow more consisely-expressed configurations, each "rule" element actually takes a list of `clusters`, `subjects`, and `actions` (**but only a singular `resource`!**), as well as a wildcard (`*`) to stand in for "any {resource|cluster|subject|action}". +At startup, `vtadmin-api` will expand these rulesets and wildcards into the individual 4-tuples discussed previously. + +#### Example + +For example, take the following configuration: + +```yaml +rules: + - resource: "*" + actions: + - "get" + - "ping" + subjects: ["*"] + clusters: ["*"] + + - resource: "*" + actions: + - "create" + - "delete" + - "put" + subjects: + - "user:andrew" + - "role:admin" + clusters: ["*"] + + - resource: "Shard" + actions: + - "emergency_failover_shard" + - "planned_failover_shard" + subjects: + - "role:admin" + clusters: + - "local" +``` + +This permits the following: +1. Any subject can `get` or `ping` any resource in any cluster. +2. Any user with the name "andrew" or role of "admin" can `create`, `delete`, or `put` any resource in any cluster. +3. Any user with the role of "admin" can perform both emergency and planned failover operations on a `Shard` in _only_ the cluster with the id of "local". + +### Clusters and Subjects + +`cluster` and `subject` values depend entirely on the details of your particular vtadmin deployment. +Possible values for `cluster`, aside from the wildcard, are the `id` of any cluster you inform `vtadmin-api` of (either via flags at start time or dynamically). + +`subject` values should be prefixed with either `user:` or `role:`. +In the case of `user:`, vtadmin's authorization check will verify the actor's `Name` value matches. +In the case of `role:`, it will verify that one of the actor's `Roles` values matches. +In code: + +```go +func (r *Rule) Allows(clusterID string, action Action, actor *Actor) bool { + if r.clusters.HasAny("*", clusterID) { + if r.actions.HasAny("*", string(action)) { + if r.subjects.Has("*") { + return true + } + + if actor == nil { + return false + } + + if r.subjects.Has(fmt.Sprintf("user:%s", actor.Name)) { + return true + } + + for _, role := range actor.Roles { + if r.subjects.Has(fmt.Sprintf("role:%s", role)) { + return true + } + } + } + } + + return false +} +``` + +Note that if you are using just authorization without authentication, you must use the wildcard subject in your rules. + +### Resources and Actions + +The following table lists all current resources vtadmin has, and the actions that can be performed on them. +Note that it's technically possible to specify a rule for an action that cannot actually be performed on a particular resource (e.g. an action of `planned_failover_shard` on a resource of `Schema`), but this has no effect on the rest of your rules. + +| API | Rule(s) Needed `(, )` form | +| :--- | :--- | +| `CreateKeyspace` | `(create, Keyspace)` | +| `CreateShard` | `(create, Shard)` | +| `DeleteKeyspace` | `(delete, Keyspace)` | +| `DeleteShards` | `(delete, Shard)` | +| `DeleteTablet` | `(delete, Tablet)` | +| `EmergencyFailoverShard` | `(emergency_failover_shard, Shard)` | +| `FindSchema` | `(get, Schema)` | +| `GetBackups` | `(get, Backup)` | +| `GetCellInfos` | `(get, CellInfo)` | +| `GetCellsAliases` | `(get, CellsAlias)` | +| `GetClusters` | `(get, Cluster)` | +| `GetGates` | `(get, VTGate)` | +| `GetKeyspace` | `(get, Keyspace)` | +| `GetKeyspaces` | `(get, Keyspace)` | +| `GetSchema` | `(get, Schema)` | +| `GetSchemas` | `(get, Schema)` | +| `GetShardReplicationPositions` | `(get, ShardReplicationPosition)` | +| `GetSrvVSchema` | `(get, SrvVSchema)` | +| `GetSrvVSchemas` | `(get, SrvVSchema)` | +| `GetTablet` | `(get, Tablet)` | +| `GetTablets` | `(get, Tablet)` | +| `GetVSchema` | `(get, VSchema)` | +| `GetVSchemas` | `(get, VSchema)` | +| `GetVtctlds` | `(get, Vtctld)` | +| `GetWorkflow` | `(get, Workflow)` | +| `GetWorkflows` | `(get, Workflow)` | +| `PingTablet` | `(ping, Tablet)` | +| `PlannedFailoverShard` | `(planned_failover_shard, Shard)` | +| `RefreshState` | `(put, Tablet)` | +| `RefreshTabletReplicationSource` | `(refresh_tablet_replication_source, Tablet)` | +| `ReloadSchemas` | `(reload, Schema)` | +| `RunHealthCheck` | `(get, Tablet)` | +| `SetReadOnly` | `(manage_tablet_writability, Tablet)` | +| `SetReadWrite` | `(manage_tablet_writability, Tablet)` | +| `StartReplication` | `(manage_tablet_replication, Tablet)` | +| `StopReplication` | `(manage_tablet_replication, Tablet)` | +| `TabletExternallyPromoted` | `(tablet_externally_promoted, Shard)` | +| `VTExplain` | `(get, VTExplain)` | +| `ValidateKeyspace` | `(put, Keyspace)` | +| `ValidateSchemaKeyspace` | `(put, Keyspace)` | +| `ValidateVersionKeyspace` | `(put, Keyspace)` | + +[authn_interface]: https://github.com/vitessio/vitess/blob/46cb4679c198c96fbe7b51f40219d8196f4284a7/go/vt/vtadmin/rbac/authentication.go#L34-L50 +[example_authn]: https://gist.github.com/ajm188/5b2c7d3ca76004a297e6e279a54c2299 + +[jaeger_plugin_example]: https://github.com/vitessio/vitess/blob/46cb4679c198c96fbe7b51f40219d8196f4284a7/go/trace/plugin_jaeger.go#L32-L36 +[go_plugin_pkg_docs]: https://pkg.go.dev/plugin + +[http_authn_handler]: https://github.com/vitessio/vitess/blob/01eab00275bbd73855c8c92876f73deb7ef62259/go/vt/vtadmin/http/handlers/authentication.go#L25-L42 +[grpc_authn_interceptors]: https://github.com/vitessio/vitess/blob/01eab00275bbd73855c8c92876f73deb7ef62259/go/vt/vtadmin/rbac/authentication.go#L52-L88 diff --git a/content/en/docs/19.0/reference/vtadmin/running_with_vtop.md b/content/en/docs/19.0/reference/vtadmin/running_with_vtop.md new file mode 100644 index 000000000..bad090be0 --- /dev/null +++ b/content/en/docs/19.0/reference/vtadmin/running_with_vtop.md @@ -0,0 +1,72 @@ +--- +title: Running with Vitess Operator +description: How to configure Vitess Kubernetes Operator to run VTAdmin +--- + +## Get Started + +{{< info >}} +VTAdmin only runs in a single Vitess cluster configuration in the Vitess operator. +{{< /info >}} + +Please also read the [Operator's Guide](../operators_guide) to learn more about configurations available and how to use them. + +## Compatibility + +Support for deploying VTAdmin in Vitess Operator has been added in [release 2.7.1](https://github.com/planetscale/vitess-operator/releases/tag/v2.7.1) onwards. + +## Overview + +Vitess Operator deploys VTAdmin in two separate containers running on the same pod. One for running the `vtadmin-api` and one for `vtadmin-web`. Please look at the [architecture docs](../architecture) for details on how they interact with each other. + +Vitess Operator then creates services on top of both `vtadmin-api` and `vtadmin-web`, which can be used to access them after either port-forwarding or assigning an external IP address to the service. + +Finally, Vitess Operator creates the `discovery.json` file automatically which is needed to connect to `vtctld` and `vtgate` services. It connects to the global `vtctld` service and per-cell service of `vtgates`, both of which Vitess Operator creates automatically. No configuration from the users is required for discovering these components. + +## Configuring VTAdmin in Vitess Operator + +The VTAdmin configuration section lives at the same level as the `vtctld` configuration in the cluster specification. + +The following options are available for configuring VTAdmin: + +- `RBAC` is a secret source. It is the role-based access control rules to use for VTAdmin API. More information on role-based access control can be found [here](../role-based-access-control). +- `Cells` is a list of strings. It is the cells where VTAdmin must be deployed. Defaults to deploying instances of VTAdmin in all cells. +- `APIAddresses` as a list of strings. Since the VTAdmin web UI runs on the client side, it needs the API address to use to query the API. We can't use the internal kubernetes service address or the ip of the pod, since they aren't visible outside the cluster. The API Address must be provided by the user based on how they export the service of VTAdmin API. In our example configuration (see below) we port-forward the service to port `14001` and therefore that is the address provided there. This value is a list because the address to be used for VTAdmin web in each cell might be different. If only 1 value is provided then, that is used for all the cells. The ideal way to deploy this would be to export each individual VTAdmin service (that we create) in each cell and attach external IPs to them and provide those IPs here. +- `Replicas` - Number of VTAdmin deployments required per cell. We setup a service on top of the web and API connections, so load-balancing comes out of the box. +- `WebResources` - Resource requests and limits for the container running the VTAdmin web server. +- `APIResources` - Resource requests and limits for the container running the VTAdmin API server. +- `ReadOnly` - Configuration to set the VTAdmin web UI to be read-only. + +Apart from the VTAdmin configuration, the image to use for the containers also needs to be provided. Currently `vitess/lite` image doesn't contain the binaries to deploy vtadmin, so the more specific `vitess/vtadmin` image needs to be used. + +## Example Configuration + +The VTAdmin configuration that is used in Vitess Operator [end to end tests](https://github.com/planetscale/vitess-operator/tree/main/test/endtoend) looks like: + +```yaml +spec: + images: + vtadmin: vitess/vtadmin:latest + vtadmin: + rbac: + name: example-cluster-config + key: rbac.yaml + cells: + - zone1 + apiAddresses: + - http://localhost:14001 + replicas: 1 + readOnly: false + apiResources: + limits: + memory: 128Mi + requests: + cpu: 100m + memory: 128Mi + webResources: + limits: + memory: 128Mi + requests: + cpu: 100m + memory: 128Mi +``` diff --git a/content/en/docs/19.0/reference/vtadmin/vtctld-api-transition.md b/content/en/docs/19.0/reference/vtadmin/vtctld-api-transition.md new file mode 100644 index 000000000..b41cbbdf9 --- /dev/null +++ b/content/en/docs/19.0/reference/vtadmin/vtctld-api-transition.md @@ -0,0 +1,55 @@ +--- +title: vtctld API Transition +weight: 3 +--- + +The following table highlights old vtctld API methods and their counterparts in the newer VTAdmin API. + +Some methods do not have a 1:1 mapping from vtctld to VTAdmin. These cases include: +- vtctld methods that are split out into many different VTAdmin methods (ex. keyspace and tablet action methods) +- vtctld methods that are not supported in VTAdmin (ex. executing a vtctl command) +- vtctld methods that we plan to support, but do not currently support, in VTAdmin +- VTAdmin methods that were not supported by vtctld API; noted here because they may be useful + +One of the main differences between vtctld and VTAdmin API is that VTAdmin API returns results across all clusters discovered by VTAdmin [cluster discovery](https://vitess.io/docs/17.0/reference/vtadmin/cluster_discovery/). VTAdmin API methods that accept a `cluster_id` parameter are methods that will return results from all clusters, unless the aforementioned filter parameter is provided. +## vtctld and VTAdmin API methods + +| Summary | `vtctld` API (old) | `vtctld` params (old) | `vtadmin` API (new) | `vtadmin` params (new)| Notes | +| -------- | ------ | -------- | ------ | -------- | -------- | +| Get cells | GET `/cells` | - | GET `/api/cells` | - | - | +| Get keyspaces | GET `/keyspaces` | - | GET `/api/keyspaces` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Get a keyspace | GET `/keyspaces/` | - | GET `/api/keyspace//` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Rebuild keyspace graph | - | - | PUT `/api/keyspace///rebuild_keyspace_graph` |
  • `allow_partial`: Specifies whether a SNAPSHOT keyspace is allowed to serve with an incomplete set of shards. Ignored for all other types of keyspaces
  • `cells`: Specifies a comma-separated list of cells to update
    • | - | +| Remove keyspace cell | - | - | PUT `/api/keyspace///remove_keyspace_cell` |
  • `cell`: Cell to be removed
  • `force`: Proceed even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data.
  • `recursive`: Also delete all tablets in that cell belonging to the specified keyspace.
    • | - | +| Validate keyspace | POST `/keyspaces/` | `action`: `ValidateKeyspace` | PUT `/api/keyspace//validate` |
  • `ping_tablets`: Indicates whether all tablets should be pinged during the validation process
    • | - | +| Validate keyspace schema | POST `/keyspaces/` | `action`: `ValidateSchemaKeyspace` | PUT `/keyspace///validate/schema` | - | - | +| Validate keyspace version | POST `/keyspaces/` | `action`: `ValidateVersionKeyspace` | PUT `/api/keyspace///validate/version` | - | - | +| Validate keyspace permissions | POST `/keyspaces/` | `action`: `ValidatePermissionsKeyspace` | To be implemented in VTAdmin | - | Need to implement in VTAdmin | +| Delete keyspace | - | - | DELETE `/api/keyspace//` |
  • `recursive`: Recursively delete all shards in the keyspace. If not specified or set to false, the keyspace must be empty (have no shards), or DeleteKeyspace returns an error
    • | - | +| Get keyspace tablets | GET `/keyspace//tablets` | `cell`, `cells` | GET `/api/tablets` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Get keyspace tablets for a specific shard | GET `/keyspace//tablets/` | `cell`, `cells` | GET `/api/tablets` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Get shards | GET `/shards` | - | GET `/api/keyspaces` |
  • `cluster_id`: Optional cluster filter
    • | In VTAdmin, to get all shards across all keyspaces, first get all keyspaces, and shards are returned within every keyspace [`keyspace.Shards`](https://github.com/vitessio/vitess/blob/main/proto/vtadmin.proto#L223) | +| Get a shard | GET `/shards/` | - | GET `/api/keyspace//` |
  • `cluster_id`: Optional cluster filter
    • | In VTAdmin, to get a shard, first get the shard's keyspace, and then filter for the shard in [`keyspace.Shards`](https://github.com/vitessio/vitess/blob/main/proto/vtadmin.proto#L223) | +| Validate a shard | POST `/shards/` | `action`: `ValidateShard` | PUT `/api/shard////validate` |
  • `ping_tablets`: Indicates whether all tablets should be pinged during the validation process.
    • | - | +| Validate shard schema | POST `/shards/` | `action`: `ValidateSchemaShard` | To be implemented in VTAdmin | - | Need to implement in VTAdmin | +| Validate shard version | POST `/shards/` | `action`: `ValidateVersionShard` | PUT `/api/shard////validate_version` | - | - | +| Validate shard permissions | POST `/shards/` | `action`: `ValidatePermissionsShard` | To be implemented in VTAdmin | - | Need to implement in VTAdmin | +| Get SrvKeyspaces for a cell | GET `/srv_keyspace/` | - | GET `/api/srvkeyspaces` |
  • `cell`: Optional cell filter
  • `cluster_id`: Optional cluster filter
    • | The VTAdmin method returns all SrvKeyspaces across all clusters and their keyspaces if the `cluster_id` parameter is not provided. | +| Get SrvKeyspaces for a specific keyspace | GET`/srv_keyspace//` | - | GET `/api/srvkeyspace//` |
  • `cell`: Optional cell filter
    • | - | +| Get all tablets by cell and/or shard | GET `/tablets` | `shard`,`cell` | GET `/api/tablets` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Get a tablet | GET `/tablets/` | - | GET `/api/tablets/` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Get tablet health | GET `/tablets//health` | - | GET `/api/tablet//healthcheck` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Get a tablet's full status | - | - | GET `/api/tablet//full_status` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Ping tablet | POST `/tablets/` | `action`: `PingTablet` | GET `/api/tablet//ping` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Refresh tablet | POST `/tablets/` | `action`: `RefreshState` | PUT `/api/tablet//refresh` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Refresh tablet replication source | - | - | PUT `/api/tablet//refresh_replication_source`|
  • `cluster_id`: Optional cluster filter
    • | - | +| Reload tablet schema | POST `/tablets/` | `action`: `ReloadSchema` | PUT `/api/tablet//reload_schema` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Set tablet to read-only | - | - | PUT `/api/tablet//set_read_only`|
  • `cluster_id`: Optional cluster filter
    • | - | +| Set tablet to read-write | - | - | PUT `/api/tablet//set_read_write` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Start replication on tablet | - | - | PUT `/api/tablet//start_replication` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Stop replication on tablet | - | - | PUT `/api/tablet//stop_replication` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Mark tablet as externally promoted | - | - | POST `/api/tablet//externally_promoted` |
  • `cluster_id`: Optional cluster filter
    • | - | +| Delete tablet | POST `/tablets/` | `action`: `DeleteTablet` | DELETE `/api/tablet/` |
  • `allow_primary`: Whether or not the primary can be deleted
  • `cluster_id`: Optional cluster filter
    • | - | +| Run a vtctl command | GET `/vtctl` | `body`: array of vtctl commands | Unsupported by VTAdmin | - | We recommend using [vtctldclient](https://vitess.io/docs/16.0/reference/programs/vtctldclient/) for running any other vtctl commands | +| Apply schema changes | POST `/schema/apply` | `keyspace`, `sql`, `ddl_strategy`, `replica_timeout_seconds` | Unsupported by VTAdmin | - | Unsupported by VTAdmin | +| Get vtctl features | GET `/features` | - | GET `/debug/env` | - | Returns the current env vars for VTAdmin API. Must have [`http-no-debug` flag](https://vitess.io/docs/14.0/reference/programs/vtadmin/#http-server-flags) set to false. | \ No newline at end of file diff --git a/content/en/docs/19.0/reference/vtctldclient-transition/_index.md b/content/en/docs/19.0/reference/vtctldclient-transition/_index.md new file mode 100644 index 000000000..6ba77d418 --- /dev/null +++ b/content/en/docs/19.0/reference/vtctldclient-transition/_index.md @@ -0,0 +1,6 @@ +--- +title: vtctldclient Transition +description: Reference material for transitioning from `vtctlclient` to `vtctldclient` +weight: 8 +--- + 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 new file mode 100644 index 000000000..3e274e166 --- /dev/null +++ b/content/en/docs/19.0/reference/vtctldclient-transition/command_diff.md @@ -0,0 +1,49 @@ +--- +title: Command Diff +weight: 3 +--- + +The following table highlights the main differences in naming between `vtctlclient` and `vtctldclient`. + +Unless noted here, command names have a one-to-one mapping between the legacy `vtctlclient` and `vtctldclient`, though output formats may have changed (e.g. `GetKeyspace` now outputs valid JSON). +For stronger guarantees of compatibility, we highly encourage programming directly against the [`VtctldServer` gRPC API][grpc_api_def]. + +[grpc_api_def]: https://github.com/vitessio/vitess/blob/04870fc27499ac64dcf6050c41fe9c44aea7099c/proto/vtctlservice.proto#L32-L33. + +### Command name differences + +| | `vtctlclient` command name (OLD) | `vtctldclient` command name (NEW) | +|-|-|-| +| | N/A | [`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyroutingrules/) | +| | `CopySchemaShard` | (deleted) | +| | `CreateLookupVindex` | (not yet migrated) | +| | `DeleteShard` | [`DeleteShards`](../../programs/vtctldclient/vtctldclient_deleteshards/) | +| | `DeleteTablet` | [`DeleteTablets`](../../programs/vtctldclient/vtctldclient_deletetablets/) | +| | `ExecuteFetchAsDba` | [`ExecuteFetchAsDBA`](../../programs/vtctldclient/vtctldclient_executefetchasdba/) | +| | `ExternalizeVindex` | (not yet migrated) | +| | `ListBackups` | [`GetBackups`](../../programs/vtctldclient/vtctldclient_getbackups/) | +| | N/A | [`GetFullStatus`](../../programs/vtctldclient/vtctldclient_getfullstatus/) | +| | N/A | [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) | +| | `GetShardReplication` | [`ShardReplicationPositions`](../../programs/vtctldclient/vtctldclient_shardreplicationpositions/) | +| | `GetSrvKeyspace` | [`GetSrvKeyspaces`](../../programs/vtctldclient/vtctldclient_getsrvkeyspaces/) | +| | N/A | [`GetSrvVSchemas`](../../programs/vtctldclient/vtctldclient_getsrvvschemas/) | +| | N/A | [`GetTabletVersion`](../../programs/vtctldclient/vtctldclient_gettabletversion/) | +| | `ListAllTablets`, `ListShardTablets`, `ListTablets` | [`GetTablets`](../../programs/vtctldclient/vtctldclient_gettablets/) | +| | 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) | +| | `UpdateSrvKeyspacePartition` | (not yet migrated) | +| | `UpdateTabletAddrs` | (deleted) | +| | `VReplicationExec` | (not yet migrated) | +| | `ValidatePermissionsKeyspace`, `ValidatePermissionsShard` | (deleted) | +| | `VtctldCommand` | N/A | +| | `WaitForFilteredReplication` | (deleted) | +| | `Workflow` | (deleted) | diff --git a/content/en/docs/19.0/reference/vtctldclient-transition/legacy_shim.md b/content/en/docs/19.0/reference/vtctldclient-transition/legacy_shim.md new file mode 100644 index 000000000..973593a77 --- /dev/null +++ b/content/en/docs/19.0/reference/vtctldclient-transition/legacy_shim.md @@ -0,0 +1,64 @@ +--- +title: Legacy Shim +weight: 2 +--- + +To make transitioning from `vtctlclient` to `vtctldclient` easier, both binaries provide shim mechanisms to run commands with each other's CLI syntaxes (and backing RPC interfaces). +Let's take each in turn. + +### `vtctldclient LegacyVtctlCommand` + +The new client provides a top-level command to run commands over the legacy `vtctlclient` interface. +This is useful to be able to use the new client "everywhere" but still be able to use functionality from the old client that has not been migrated yet (e.g. `Reshard`). + +For example: + +``` +$ vtctldclient --server ":15999" LegacyVtctlCommand -- Reshard show +``` + +You can also use this to transition a command in two phases, for example: + +1. Start with the existing invocation: + +```shell +vtctlclient --server ":15999" -- AddCellInfo --root /mycell --server_address "${some_topo_server}:1234" +``` + +2. Then "switch" to the new client but use the old code and syntax: + +```shell +vtctldclient --server ":15999" LegacyVtctlCommand -- AddCellInfo --root /mycell --server_address "${some_topo_server}:1234" +``` + +3. Finally, update the command to use the new code and CLI (notice the flag change from `--server_address` to `--server-address` and the removal of the `--`): + +```shell +vtctldclient --server ":15999" AddCellInfo --root /mycell --server-address "${some_topo_server}:1234" +``` + +### `vtctlclient VtctldCommand` + +Conversely, the _old_ client also provides a top-level command to run commands over the new `vtctldclient` interface. +This is useful to migrate your scripts over before necessarily deploying the new, separate binary everywhere. + +Taking the same example as above, in reverse: + + +1. Start with the existing invocation: + +```shell +vtctlclient --server ":15999" -- AddCellInfo --root /mycell --server_address "${some_topo_server}:1234" +``` + +2. Then switch to the new code and syntax (note the flag change from `--server_address` to `--server-address`) _without_ switching the invoked client binary: + +```shell +vtctlclient --server ":15999" -- VtctldCommand AddCellInfo --root /mycell --server-address "${some_topo_server}:1234" +``` + +3. Finally, update the command to use the new binary, cleaning up the extra flag separators (`--`) as well. + +```shell +vtctldclient --server ":15999" AddCellInfo --root /mycell --server-address "${some_topo_server}:1234" +``` diff --git a/content/en/docs/19.0/reference/vtctldclient-transition/overview.md b/content/en/docs/19.0/reference/vtctldclient-transition/overview.md new file mode 100644 index 000000000..28b59bee1 --- /dev/null +++ b/content/en/docs/19.0/reference/vtctldclient-transition/overview.md @@ -0,0 +1,45 @@ +--- +title: Overview +weight: 1 +--- + +Vitess v14 introduced a new, strongly-typed gRPC interface for cluster management, called [`VtctldServer`][grpc_vtctld_server]. +You can refer to the [original RFC][vtctld_server_rfc] for details, but the essential difference is the legacy `VtctlServer` implementation had a single, streaming RPC with the signature: + +```protobuf +rpc ExecuteVtctlCommand(ExecuteVtctlCommandRequest) returns (stream ExecuteVtctlCommandResponse); +``` + +
    + +The new interface has individual RPCs for each command, with command-specific request and response types. +Most RPCs are unary, while a few (`Backup`, for example) are streaming RPCs. + +### Enabling the new service + +In order to enable the new service interface, add `grpc-vtctld` to the list of services in the `--service_map` flag provided to `vtctld`. +Both the new and old interfaces may be run from the same `vtctld` instance, so during transition, most users will set `--service_map="grpc-vtctl,grpc-vtctld"`. + +### Transitioning clients + +The new service implementation comes with a corresponding client implementation, which is called [`vtctldclient`][vtctldclient_docs]. +Most existing commands can be run directly from the new client, for example: + +``` +$ vtctldclient --server ":15999" GetCellInfoNames +zone1 +``` + +
    + +For the full list of commands, as well as the flags they support, you can refer to the [client documentation][vtctldclient_docs]. + +Not all commands are currently implemented, but both the old ([`vtctlclient`][vtctlclient_docs]) and new (`vtctldclient`) clients provide shim mechanisms to use the new and old interfaces, respectively. +That is to say: `vtctlclient VtctldCommand ...` allows you to run new `vtctldclient` CLI commands, and `vtctldclient LegacyVtctlCommand ...` allows you to run old `vtctlclient` CLI commands. +For more details, refer to [the documentation][legacy_shim_docs]. + +[grpc_vtctld_server]: ../../programs/vtctld/#grpc-vtctld-mdash-new-as-of-v14 +[vtctld_server_rfc]: https://github.com/vitessio/vitess/issues/7058 +[vtctldclient_docs]: ../../programs/vtctldclient/ +[vtctlclient_docs]: ../../programs/vtctl/ +[legacy_shim_docs]: ../legacy_shim/ diff --git a/content/en/docs/19.0/reference/vtorc/_index.md b/content/en/docs/19.0/reference/vtorc/_index.md new file mode 100644 index 000000000..a20890d78 --- /dev/null +++ b/content/en/docs/19.0/reference/vtorc/_index.md @@ -0,0 +1,5 @@ +--- +title: VTOrc +weight: 9 +--- + diff --git a/content/en/docs/19.0/reference/vtorc/architecture.md b/content/en/docs/19.0/reference/vtorc/architecture.md new file mode 100644 index 000000000..400f69c23 --- /dev/null +++ b/content/en/docs/19.0/reference/vtorc/architecture.md @@ -0,0 +1,46 @@ +--- +title: Architecture +--- + +# Overview + +VTOrc is the automated fault detection and repair tool of Vitess. + +It follows the following high level steps for finding problems and fixing them - +- It queries the `vttablets` every `instance-poll-time` to gather information about the underlying MySQL instances. +- It also contacts the topology-server every `topo-information-refresh-duration` to know the desired state of the topology. +- Based on the information collected, VTOrc finds if there are any configuration issue on any of the MySQL instances and takes appropriate actions. +- These are then fixed by issuing RPCs to the associated `vttablets` + +```mermaid +stateDiagram-v2 + start: Collect Information + topoServer: Topology Server + vttablets: Vttablets + infoCollected: Information Received + problems: Problems Found + fixes: Run Fixes + + start --> topoServer: Every `topo-information-refresh-duration` + start --> vttablets: Every `instance-poll-time` + topoServer --> infoCollected: Keyspace and Vttablet records + vttablets --> infoCollected: MySQL information + infoCollected --> problems: Analyze collected information + problems --> fixes: RPCs to Vttablets +``` + +# Coordination among VTOrc instances and `vtctld` + +Users are encouraged to run multiple instances of VTOrc monitoring the same cluster because VTOrc too, like any other service is liable to failure +for reasons out of its control. Also, users run `vtctld` instances which can be used to run commands which alter the desired topology ([PlannedReparentShard](../../../user-guides/configuration-advanced/reparenting/#plannedreparentshard-planned-reparenting)) +and durability requirements ([SetKeyspaceDurabilityPolicy](../../programs/vtctldclient/vtctldclient_setkeyspacedurabilitypolicy/)). + +The most logical question that arises is how do we ensure coordination between multiple VTOrc instances and `vtctld`. + +We do so by using the existing central topology-server. Each of these services, acquire a shard lock before it proceeds to run any fixes. +This ensures that there is only one actor at any given point of time trying to alter the cluster. + +Another cause of concern could be recoveries run on stale data collected by VTOrc. +Since VTOrc instances use a polling method to load the information they use for fault detection, they can sometimes read outdated information. +To prevent VTOrc instances from running incorrect/unnecessary recoveries, all VTOrc instances refresh their local information that they require +for the fix after acquiring a shard lock. diff --git a/content/en/docs/19.0/reference/vtorc/img/VTOrc-Recent-Recoveries.png b/content/en/docs/19.0/reference/vtorc/img/VTOrc-Recent-Recoveries.png new file mode 100644 index 000000000..4e565bc72 Binary files /dev/null and b/content/en/docs/19.0/reference/vtorc/img/VTOrc-Recent-Recoveries.png differ diff --git a/content/en/docs/19.0/reference/vtorc/running_with_vtop.md b/content/en/docs/19.0/reference/vtorc/running_with_vtop.md new file mode 100644 index 000000000..75f9c932e --- /dev/null +++ b/content/en/docs/19.0/reference/vtorc/running_with_vtop.md @@ -0,0 +1,40 @@ +--- +title: Running with Vitess Operator +description: How to configure Vitess Kubernetes Operator to run VTOrc +--- + +## Get Started + +The Vitess operator deploys one VTOrc instance for each keyspace that it is configured for. Please look at the [VTOrc reference page](../../programs/vtorc) +to know all the flags that VTOrc accepts. + +## Configuring VTOrc in Vitess Operator + +The VTOrc can be configured to run for a given keyspace by specifying the `vitessOrchestrator` specification as part of the `keyspace` spec. +Resource limits and requests can be specified as part of the configuration and the default behaviour of VTOrc can be changed by specifying any +desired flags in the `extraFlags` field. + +The VTOrc UI runs on the port `15000` of the container and port-forwarding can be setup to access it. + +## Example Configuration + +An example deployment from the VTOrc [end to end test](https://github.com/planetscale/vitess-operator/tree/main/test/endtoend) on the Vitess Operator looks like: +```yaml +keyspaces: + - name: commerce + durabilityPolicy: semi_sync + turndownPolicy: Immediate + vitessOrchestrator: + resources: + limits: + memory: 128Mi + requests: + cpu: 100m + memory: 128Mi + extraFlags: + recovery-period-block-duration: 5s +``` + +The full configuration file is available [here](https://github.com/planetscale/vitess-operator/blob/main/test/endtoend/operator/101_initial_cluster_vtorc_vtadmin.yaml). + + diff --git a/content/en/docs/19.0/reference/vtorc/ui_api_metrics.md b/content/en/docs/19.0/reference/vtorc/ui_api_metrics.md new file mode 100644 index 000000000..90cdfca2b --- /dev/null +++ b/content/en/docs/19.0/reference/vtorc/ui_api_metrics.md @@ -0,0 +1,48 @@ +--- +title: UI, API and Metrics +--- + +# UI + +In order to use UI, `--port` flag has to be provided. + +Currently, the `/debug/status` lists the recent recoveries that VTOrc has performed. + +![VTOrc-recent-recoveries](../img/VTOrc-Recent-Recoveries.png) + +# APIs + +VTOrc supports the following APIs which can be used for monitoring and changing the behaviour of VTOrc. + + | New API | Additional notes | +|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `/api/problems` | This API lists all the instances that have any problems in them. The problems range from replication not running to errant GTIDs. The new API also supports filtering using the keyspace and shard name | +| `/api/disable-global-recoveries` | This API disables the global recoveries in VTOrc. This makes it so that VTOrc doesn't repair any failures it detects. | + | `/api/enable-global-recoveries` | This API enables the global recoveries in VTOrc. | + | `/debug/health` | This API outputs the health of the VTOrc process. | + | `/debug/liveness` | This API outputs the liveness of the VTOrc process. | +| `/api/replication-analysis` | This API shows the replication analysis of VTOrc. Output is in JSON format. | +| `/api/errant-gtids` | This API shows the tablets that have errant GTIDs as detected by VTOrc. Output is in JSON format. This API supports filtering by keyspace and shard name. | + +# Metrics + +Metrics are available to be seen on the `/debug/vars` page. VTOrc exports the following metrics: + +| Metric | Usage | +|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `PendingRecoveries` | The number of recoveries in progress which haven't completed. | +| `RecoveriesCount` | The number of recoveries run. This is further subdivided for all the different recoveries. | +| `SuccessfulRecoveries` | The number of succesful recoveries run. This is further subdivided for all the different recoveries. | +| `FailedRecoveries` | The number of recoveries that failed. This is further subdivided for all the different recoveries. | +| `ErrantGtidTabletCount` | The number of tablets with errant GTIDs as detected by VTOrc. | +| `DetectedProblems` | Binary gauge that shows the active problems that VTOrc has detected. This is further subdivided by TabletAlias, Keyspace, and Shard. | +| `planned_reparent_counts` | Number of times Planned Reparent Shard has been run. It is further subdivided by the keyspace, shard and the result of the operation. | +| `emergency_reparent_counts` | Number of times Emergency Reparent Shard has been run. It is further subdivided by the keyspace, shard and the result of the operation. | +| `reparent_shard_operation_timings` | Timings of reparent shard operations indexed by the type of operation. | + + +{{< info >}} +If there is some information about VTOrc that you would like to see +on the `/debug/status` page or support for some API or metrics to be added, please let us know in [slack](https://vitess.io/slack) +in the [#feat-vtorc](https://vitess.slack.com/archives/C02GSRZ8XAN) channel +{{< /info >}} diff --git a/content/en/docs/19.0/user-guides/_index.md b/content/en/docs/19.0/user-guides/_index.md new file mode 100644 index 000000000..32844607d --- /dev/null +++ b/content/en/docs/19.0/user-guides/_index.md @@ -0,0 +1,8 @@ +--- +title: User Guides +description: Task-based guides for common usage scenarios +weight: 4 +aliases: ['/user-guide/client-libraries.html', '/docs/user-guides/'] +--- + +We recommend running through a [get started](../get-started) on your favorite platform before running through user guides. diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/_index.md b/content/en/docs/19.0/user-guides/configuration-advanced/_index.md new file mode 100644 index 000000000..93e1c5d63 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/_index.md @@ -0,0 +1,5 @@ +--- +title: Advanced Configuration +description: User guides covering advanced configuration concepts +weight: 5 +--- diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/authorization.md b/content/en/docs/19.0/user-guides/configuration-advanced/authorization.md new file mode 100644 index 000000000..df57e6dbf --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/authorization.md @@ -0,0 +1,265 @@ +--- +title: Authorization +weight: 10 +aliases: ['/docs/user-guides/authorization/'] +--- + +A common question is how to enforce fine-grained access control in Vitess. +This question comes up because Vitess uses connection pooling with fixed +MySQL users at the VTTablet level, and implements its own authentication +at the VTGate level. As a result, you cannot use the normal MySQL GRANTs +system to give certain application-level MySQL users more or less permissions +than others. + +The MySQL GRANT system is very extensive, and we have not reimplemented +all of this functionality in Vitess. What we have done is to enable you +to provide authorization via table-level ACLs, with a few basic +characteristics: + + * Individual users can be assigned 3 levels of permissions: + * Read (corresponding to read DML, e.g. `SELECT`) + * Write (corresponding to write DML, e.g. `INSERT`, `UPDATE`, `DELETE`) + * Admin (corresponding to DDL, e.g. `ALTER TABLE`) + * Permissions are applied on a specified set of tables, which can be + enumerated or specified by regex. + +## VTTablet parameters for table ACLs + +Note that the Vitess authorization via ACLs are applied at the VTTablet +level, as opposed to on VTGate, where authentication is enforced. +There are a number of VTTablet command line parameters that control the +behavior of ACLs. Let's review these: + + * `--enforce-tableacl-config`: Set this to `true` to ensure VTTablet will not + start unless there is a valid ACL configuration. This is used to + catch misconfigurations resulting in blanket access to authenticated + users. + * `--queryserver-config-enable-table-acl-dry-run`: Set to `true` to check the + table ACL at runtime, and only emit the + [TableACLPseudoDenied](../../configuration-basic/monitoring) + metric if a request would have been blocked. The request is then + allowed to pass, even if the ACL determined it should + be blocked. This can be used for testing new or updated ACL policies. + Default is `false`. + * `--queryserver-config-strict-table-acl`: Set to `true` to enforce table ACL + checking. **This needs to be enabled for your ACLs to have any effect.** + Any users that are not specified in an ACL policy will be denied. + Default is `false`. + * `--queryserver-config-acl-exempt-acl`: Allows you to specify the name + of an ACL (see below for format) that is exempt from enforcement. + Allows you to separate the rollout and the subsequent enforcement of + a specific ACL. + * `--table-acl-config`: Path to a file defining the table ACL config. + * `--table-acl-config-reload-interval`: How often the `table-acl-config` + should be reloaded. Set this to allow you to update the ACL file on + disk, and then have VTTablet automatically reload the file within this + period. Default is not to reload the ACL file after VTTablet startup. + Note that even if you do not set this parameter, you can always force + VTTablet to reload the ACL config file from disk by sending a SIGHUP + signal to your VTTablet process. + +## Warning regarding ACL reloading + +If you choose to reload the ACL config manually or on an interval, +and you are using the `-enforce-tableacl-config` option, your VTTablet +processes **will exit** if your table ACL config file contains an invalid +configuration at reload time. While this might be unexpected, this ensures +the highest level of security. Accordingly, it is very important to test +your ACL config thoroughly before applying, pay attention to access +permissions on the ACL config file, etc. + +## Format of the table ACL config file + +The file specified in the `--table-acl-config` parameter above is a JSON +file with the following example to explain the format: + +```json +{ + "table_groups": [ + { + "name": "aclname", + "table_names_or_prefixes": [ + "%" + ], + "readers": [ + "vtgate-user1" + ], + "writers": [ + "vtgate-user2" + ], + "admins": [ + "vtgate-user3" + ] + }, + { "... more ACLs here if necessary ..." } + ] +} +``` + +Notes: + + * `name`: This is the name of the ACL (`aclname` in the example above) and is + what needs to be specified in `--queryserver-config-acl-exempt-acl`, + if you need to exempt a specific ACL from enforcement. + * `table_names_or_prefixes`: A list of strings and/or regexes that allow + a rule to target a specific table or set of tables. Use `%` as in the + example to specify all tables. Note that only the SQL `%` "regex" + wildcard is supported here at the moment. + * `readers`: A list of VTGate users, specified by their [UserData](../../configuration-advanced/user-management/#userdata) + field in the authentication specification, that are allowed to read the + tables targeted by this ACL rule. Typically allows `SELECT`. + * `writers`: A list of VTGate users that are allowed to write to the tables + targeted by this ACL rule. Typically allows `INSERT`, `UPDATE` and `DELETE`. + * `admins`: A list of VTGate users that are allowed admin privileges on + the tables targeted by this ACL rule. Typically allows DDL privileges, + e.g. `ALTER TABLE`. Note that this also includes some commands that might + be thought of as DML, which are really DDL, like `TRUNCATE`) + * Note that `writers` privilege does not imply `readers` privilege, and `admins` + privilege does not imply `readers` or `writers`. You need to therefore + add your users to each list explicitly if you want them to have that + level of access. + * You cannot use multiple ACL rules to target the same (sub)set of tables. + Therefore the tablenames specified by `table_names_or_prefixes` + (or expanded by regexes) need to be non-overlapping between ACL rules. + Additionally, you cannot have duplicate tablenames or overlapping regexes + in the `table_names_or_prefixes` list in a single ACL rule. + +## Example + +Let's assume your Vitess cluster already has two keyspaces setup: + + * `keyspace1` with a single table `t` that should only be accessed by `myuser1` + * `keyspace2` with a single table `t` that should only be accessed by `myuser2` + +For the VTTablet configuration for `keyspace1`: +```sh +$ cat > acls_for_keyspace1.json << EOF +{ + "table_groups": [ + { + "name": "keyspace1acls", + "table_names_or_prefixes": ["%"], + "readers": ["myuser1", "vitess"], + "writers": ["myuser1", "vitess"], + "admins": ["myuser1", "vitess"] + } + ] +} +EOF + +$ vttablet --init_keyspace "keyspace1" --table-acl-config=acls_for_keyspace1.json --enforce-tableacl-config --queryserver-config-strict-table-acl ........ +``` + +Note that the `%` specifier for `table_names_or_prefixes` translates to +"all tables". + +Do the same thing for `keyspace2`: +```sh +$ cat > acls_for_keyspace2.json << EOF +{ + "table_groups": [ + { + "name": "keyspace2acls", + "table_names_or_prefixes": ["%"], + "readers": ["myuser2", "vitess"], + "writers": ["myuser2", "vitess"], + "admins": ["myuser2", "vitess"] + } + ] +} +EOF + +$ vttablet --init_keyspace "keyspace2" --table-acl-config=acls_for_keyspace2.json --enforce-tableacl-config --queryserver-config-strict-table-acl ........ +``` + +With this setup, the `myuser1` and `myuser2` users can only access their respective keyspaces, but the `vitess` +user can access both. + +```sh +# Attempt to access keyspace1 with myuser2 credentials through vtgate +$ mysql -h 127.0.0.1 -u myuser2 -ppassword2 -D keyspace1 -e "select * from t" +ERROR 1045 (HY000) at line 1: vtgate: http://vtgate-zone1-7fbfd8cc47-tchbz:15001/: target: keyspace1.-80.primary, used tablet: zone1-476565201 (zone1-keyspace1-x-80-replica-1.vttablet): vttablet: rpc error: code = PermissionDenied desc = table acl error: "myuser2" [] cannot run PASS_SELECT on table "t" (CallerID: myuser2) +target: keyspace1.80-.primary, used tablet: zone1-1289569200 (zone1-keyspace1-80-x-replica-0.vttablet): vttablet: rpc error: code = PermissionDenied desc = table acl error: "myuser2" [] cannot run PASS_SELECT on table "t" (CallerID: myuser2) +$ +``` + +Whereas myuser1 is able to access its keyspace without error: +```sh +$ mysql -h 127.0.0.1 -u myuser1 -ppassword1 -D keyspace1 -e "select * from t" +$ +``` +## Negative ACLs + +If you want to set up an authorization structure like the following: + + * Assume a database with the tables `t1`, `t2` and `t3`, and the database + (`vtgate`) users `regular` and `privileged`. + * Give read and write access to only tables `t1` and `t2` to user `regular`. + * **Only** give user `privileged` access to read or write table `t3`. + +You will need to construct an ACL config with two ACLs, and enumerate all the necessary table names in each ACL +(`t1` and `t2` in the first ACL; `t3` in the second ACL). This type of configuration could be called "completely specified". + +However, every time a non-privileged table is added to the schema, the +ACL config needs to be updated to add the table name to the config, or +user `regular` will not have access to it. For schemas with large numbers +of tables, and that change frequently, this can be a burden. + +In general, it is not possible to express a "negative" target ACL in Vitess' +ACL config syntax, e.g.: `Give this user access to all tables except these +specific ones`. It is possible to express an ACL config that is +equivalent to the above "completely specified" ACL config, but somewhat +easier to manage, even for large numbers of tables. + +Consider the following example: + + * Your schema has a 100+ tables. + * You regularly add new tables. + * You have a special set of tables called `secret` and `supersecret` + that you only want a specific `vtgate` user called `super` to have + access to. + * You have 3 other users: + * `readonly` for read access to all tables, except `secret` and + `supersecret` + * `readwrite` for read and write access to all tables, except `secret` + and `supersecret` + * `dba` for read, write and admin access to all tables, except + `secret` and `supersecret`. + * You only a few other tables that start with the letter `s`, called + `s1`, `s2`, `s3`. + * We assume you do not use table names with upper case or other + characters. + +The idea of this configuration is that you construct access to the +non-sensitive data using wildcards of table names for each letter +of the alphabet. You then only need to specify table names fully for +the letter of the alphabet that our "special" tables start +with. In other words this still requires us to specify a list of table names, but +only for the letters of the alphabet that the "special" tables start +with. + +Here is the ACL config that satisfies the requirements: + +```json +{ + "table_groups": [ + { + "name": "acl1", + "table_names_or_prefixes": ["a%", "b%", "c%", "d%", "e%", "f%", "g%", "h%", "i%", "j%", "k%", "l%", "m%", "n%", "o%", "p%", "q%", "r%", "t%", "u%", "v%", "w%", "x%", "y%", "z%", "s1", "s2", "s3"], + "readers": ["readonly", "readwrite", "dba"], + "writers": ["readwrite", "dba"], + "admins": ["dba"] + }, + { + "name": "acl2", + "table_names_or_prefixes": ["secret", "supersecret"], + "readers": ["super"], + "writers": ["super"], + "admins": ["super"] + } + ] +} +``` + +Now, with the above ACL config, you only need to update the ACL config +if you add a new table that starts with the letter `s`. diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/buffering-scenarios.md b/content/en/docs/19.0/user-guides/configuration-advanced/buffering-scenarios.md new file mode 100644 index 000000000..31dda16ae --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/buffering-scenarios.md @@ -0,0 +1,573 @@ +--- +title: VTGate Buffering Scenarios +weight: 12 +aliases: ['/docs/reference/features/vtgate-buffering', +'/docs/reference/programs/vtgate'] +--- + +For documentation on buffering behaviors please see +[VTGate Buffering](../../../reference/features/vtgate-buffering/). +In this guide we are going to go through a few scenarios involving buffering to +see the practical behaviors. There are several parameters to tune for buffering +so, we will be using a python utility [gateslap](https://github.com/planetscale/gateslap) +to generate traffic and simulate an application. You will need three terminal +windows for these exercises: + + * terminal 1 - for manipulating the vtgate process + * terminal 2 - for sending simulated traffic to vtgate; gateslap + * terminal 3 - to send PlannedReparentShard (PRS) commands and retrieve metrics + +## Setup + +These scenarios will be building off of the +[local getting started guide](../../../get-started/local/). + +#### Terminal 1 + +1.) Locate the vtgate process, copy the process information to your notes for +future use; then kill the process: + +``` +Terminal 1 + $ ps aux | head -1; ps aux | grep vtgat[e] + $ pkill vtgate +``` + +2.) From your notes, paste in the vtgate command you have previously copied into +the terminal window and hit enter: + + +``` +Terminal 1 + $ vtgate --topo_implementation etcd2 --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global --log_dir ~/github/vitess/examples/local/vtdataroot/tmp \ + --log_queries_to_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate_querylog.txt \ + --port 15001 --grpc_port 15991 --mysql_server_port 15306 --mysql_server_socket_path /tmp/mysql.sock \ + --cell zone1 --cells_to_watch zone1 --tablet_types_to_wait PRIMARY,REPLICA \ + --service_map grpc-vtgateservice --pid_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate.pid \ + --mysql_auth_server_impl none +``` + +#### Terminal 2: + +3.) In a NEW terminal window download and configure gateslap. This utility will +be used to simulate traffic on Vitess. The virtualenv and source commands are +optional: + +``` +Terminal 2 + $ git clone https://github.com/planetscale/gateslap.git + $ cd gateslap + $ virtualenv venv + $ source venv/bin/activate + $ sudo python3 setup.py install +``` + +4.) You may do a test run of this script which will create a table called `t1` +in the commerce schema. You may hit "CTRL + C" at anytime to stop the traffic. +By default this will create 2 persistent, 2 pooled, and 2 oneoff MySQL +connections and it will drop the `t1` table when it is complete, or when the +SIGINT signal is given. You can change the behavior by modifying the +`slapper.ini` file. + +``` +Terminal 2 + (venv) $ gateslap + (venv) CTRL + C +``` + +#### Terminal 3: + +5.) In a third terminal window we will prepare the vtctldclient to do a +PlannedReparentShard (PRS). Note, `time` is optional but it is useful +for measuring how long the operation takes. + +``` +Terminal 3 + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` +--- + +## Scenarios + +### Scenario 1: Default behavior + +By default there are no buffering mechanisms in place on vtgate. +In this configuration gateslap is configured to exit immediately when an +error is encountered. + +``` +Terminal 2: + (venv) $ gateslap examples/01_light_traffic.ini +``` + +As soon as traffic is sent issue the PlannedReparentShard command: + +``` +Terminal 3: + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` + +#### Results: + +As soon as you issue the PRS operation, you will notice SQL statements begin +to drop and the utility exits. The error code we get from vtgate is `1105` with +the message `target: commerce.0.primary: primary is not serving, there is a +reparent operation in progress`. With no buffering in place it is exclusively +the job of the application to handle this error appropriately, to ensure data +is not lost. Below we can look at buffering metrics. + +```sh +$ curl -s localhost:15001/metrics | grep -v '^#' | grep buffer_requests +vtgate_buffer_requests_buffered{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_buffered_dry_run{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_drained{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="ContextDone",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="WindowExceeded",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Disabled",shard_name="0"} 33 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastFailoverTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastReparentTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Shutdown",shard_name="0"} 0 +``` + +NOTE: reviewing the buffered request metrics from vtgate, nothing was buffered +during this event. + + +### Scenario 2: Solving with error Handling + +One approach to preventing these `1105` errors is to handle them in the +application. In the next example we will configure gateslap to retry the MySQL +connection 10 times before it quits. Each time it will wait five seconds +(5000ms) for a `PRIMARY` tablet to return. + +``` +Terminal 2: + Ctrl + C + (venv) $ gateslap examples/02_light_traffic_error_handling.ini +``` + +As soon as traffic is sent issue the PlannedReparentShard command: + +``` +Terminal 3: + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` + +#### Results: + +The PlannedReparentShard event occurs, and the application recognizes the `1105` +error. The error is displayed on screen and the application sleeps for 5 +seconds before retrying the connection. During the error handling the connection +is retried, and it is able to execute the SQL and continue processing. Nothing +is getting buffered in vtgate. + +```sh +$ curl -s localhost:15001/metrics | grep -v '^#' | grep buffer_requests +vtgate_buffer_requests_buffered{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_buffered_dry_run{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_drained{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="ContextDone",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="WindowExceeded",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Disabled",shard_name="0"} 122 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastFailoverTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastReparentTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Shutdown",shard_name="0"} 0 +``` + +NOTE: Once again no queries are being buffered in these examples. + + +### Scenario 3: Solving with Buffering + +Another approach to this problem, is to employ buffering on vtgate. It is highly +recommended to use both buffering and error handling in your code; however for +purposes of highlighting buffering we will disable the error handling in this +example. + +First we will need to reconfigure vtgate running in your terminal 1. + +``` +Terminal 1: + Hit "Ctrl + C" to kill the vtgate process +``` + +Add the vtgate arguments needed to implement buffering. We are only implementing +basic buffering functionality. Notice the additional flag we are adding +to our vtgate process: `-enable_buffer=1` + +``` +Terminal 1: + $ vtgate --topo_implementation etcd2 --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global --log_dir ~/github/vitess/examples/local/vtdataroot/tmp \ + --log_queries_to_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate_querylog.txt \ + --port 15001 --grpc_port 15991 --mysql_server_port 15306 --mysql_server_socket_path /tmp/mysql.sock \ + --cell zone1 --cells_to_watch zone1 --tablet_types_to_wait PRIMARY,REPLICA \ + --service_map grpc-vtgateservice --pid_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate.pid \ + --mysql_auth_server_impl none --enable_buffer=1 +``` + +We're using the `01_light_traffic.ini` which has error handling disabled. + +``` +Terminal 2: + Ctrl + C + (venv) $ gateslap examples/01_light_traffic.ini +``` + +As soon as traffic is sent issue the PlannedReparentShard command: + +``` +Terminal 3: + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` + +#### Results: + +Shortly after the PRS command is issued, the SQL statements pause momentarily. +During this time a message is logged to the terminal console window: + +``` +E1215 15:35:47.712589 251262 healthcheck.go:487] Adding 1 to PrimaryPromoted counter for target: keyspace:"commerce" shard:"0" tablet_type:REPLICA, tablet: zone1-0000000101, tabletType: PRIMARY +``` + +After this process completes, SQL statements resume processing once again. When +we take a look at stats (shown below) we will see for the first time records of +buffering occurring on the vtgate. + +```sh +$ curl -s localhost:15001/metrics | grep -v '^#' | grep buffer_requests +vtgate_buffer_requests_buffered{keyspace="commerce",shard_name="0"} 6 +vtgate_buffer_requests_buffered_dry_run{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_drained{keyspace="commerce",shard_name="0"} 6 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="ContextDone",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="WindowExceeded",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Disabled",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastFailoverTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastReparentTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Shutdown",shard_name="0"} 0 +``` + +NOTE: You will see each of our 6 established connections were buffered during +the PRS event. + + + +### Scenario 4: Quickly issued PRS events + +In this scenario we are going to look at the buffering behavior when quickly +issuing several PlannedReparentShard operations. Restart the VTGate before +proceeding to reset the buffering statistics. + +Restart the vtgate process to clear metrics: + +``` +Terminal 1: + Ctrl + C + $ vtgate --topo_implementation etcd2 --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global --log_dir ~/github/vitess/examples/local/vtdataroot/tmp \ + --log_queries_to_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate_querylog.txt \ + --port 15001 -grpc_port 15991 --mysql_server_port 15306 --mysql_server_socket_path /tmp/mysql.sock \ + --cell zone1 -cells_to_watch zone1 --tablet_types_to_wait PRIMARY,REPLICA \ + --service_map grpc-vtgateservice -pid_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate.pid \ + --mysql_auth_server_impl none --enable_buffer=1 +``` + +``` +Terminal 2: + Ctrl + C + (venv) $ gateslap examples/01_light_traffic.ini + +``` + +As soon as traffic is sent issue the PlannedReparentShard commands. Note there +is a 5 second sleep commands between the PRS statements. + +``` +Terminal 3: + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 && sleep 5 && time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` + +#### Results: + +In this scenario, back to back PRS events were issued, only 5 seconds apart. +Due to the close nature of these events, buffering is disabled to protect Vitess +against events where PRS may be issued in a looping fashion. This behavior is +adjustable with the vtgate flag `--buffer_min_time_between_failovers`. + +```sh +$ curl -s localhost:15001/metrics | grep -v '^#' | grep buffer_requests +vtgate_buffer_requests_buffered{keyspace="commerce",shard_name="0"} 6 +vtgate_buffer_requests_buffered_dry_run{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_drained{keyspace="commerce",shard_name="0"} 6 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="ContextDone",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="WindowExceeded",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Disabled",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastFailoverTooRecent",shard_name="0"} 28 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastReparentTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Shutdown",shard_name="0"} 0 +``` + +NOTE: Here we will see the `LastFailoverTooRecent` metric to let us know these +PRS events are too close together for the vtgate to buffer again. You will also +see 6 events which were buffered from the first PRS event. + +#### Preventing this issue + +We can prevent this issue by implementing error handling, which your application +should be doing. Another way to handle the issue is to ensure you are waiting +for the `--buffer_min_time_between_failovers` timer to expire before issuing +the next PlannedReparentShard command. + + + +### Scenario 5: Too many connections + +Another aspect to be aware of is the `--buffer_size`. For this scenario we will +be setting the buffer size lower than the number of connections from the +application. As we're using 6 connections in our example we will set the +`buffer_size` down from the default of `1000` to `4`. + +Restart the vtgate process to clear metrics: + +``` +Terminal 1: + Hit "Ctrl + C" to kill the vtgate process + + $ vtgate --topo_implementation etcd2 --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global --log_dir ~/github/vitess/examples/local/vtdataroot/tmp \ + --log_queries_to_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate_querylog.txt \ + --port 15001 --grpc_port 15991 --mysql_server_port 15306 --mysql_server_socket_path /tmp/mysql.sock \ + --cell zone1 --cells_to_watch zone1 --tablet_types_to_wait PRIMARY,REPLICA \ + --service_map grpc-vtgateservice --pid_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate.pid \ + --mysql_auth_server_impl none --enable_buffer=1 --buffer_size=4 +``` + +``` +Terminal 2: + Ctrl + C + (venv) $ gateslap examples/01_light_traffic.ini +``` + +``` +Terminal 3: + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` + +#### Results: + +Two of the 6 threads will die, as they were unable to obtain a slot during the +buffering event. The remaining 4 threads will be buffered and will continue to +process in their thread. To avoid this issue you should set your buffer_size to +the estimated amount of requests you expect to get during the PRS event. + +```sh +$ curl -s localhost:15001/metrics | grep -v '^#' | grep buffer_requests +vtgate_buffer_requests_buffered{keyspace="commerce",shard_name="0"} 8 +vtgate_buffer_requests_buffered_dry_run{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_drained{keyspace="commerce",shard_name="0"} 4 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="BufferFull",shard_name="0"} 4 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="ContextDone",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="WindowExceeded",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Disabled",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastFailoverTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastReparentTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Shutdown",shard_name="0"} 0 +``` + +NOTE: Here we can see the `BufferFull` metric set to 4 to let us know the buffer +had an overflow. + + + +### Scenario 6: Buffer time too Short + +In this scenario we are going to set the `buffer_window` to a short period of +time, and hit the vtgate a bit harder with a different configuration file. + +Restart the vtgate process to clear metrics: + +``` +Terminal 1: + Hit "Ctrl + C" to kill the vtgate process + + $ vtgate --topo_implementation etcd2 --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global --log_dir ~/github/vitess/examples/local/vtdataroot/tmp \ + --log_queries_to_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate_querylog.txt \ + --port 15001 --grpc_port 15991 --mysql_server_port 15306 --mysql_server_socket_path /tmp/mysql.sock \ + --cell zone1 --cells_to_watch zone1 --tablet_types_to_wait PRIMARY,REPLICA \ + --service_map grpc-vtgateservice --pid_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate.pid \ + --mysql_auth_server_impl none --enable_buffer=1 --buffer_window=1s +``` + +``` +Terminal 2: + Ctrl + C + (venv) $ gateslap examples/03_short_timeout.ini +``` + +``` +Terminal 3: + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` + +#### Results: + +In these results, we see a few SQL statements fail to buffer. They display +the standard `1105` error we've seen previously. + +```sh +$ curl -s localhost:15001/metrics | grep -v '^#' | grep buffer_requests +vtgate_buffer_requests_buffered{keyspace="commerce",shard_name="0"} 10 +vtgate_buffer_requests_buffered_dry_run{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_drained{keyspace="commerce",shard_name="0"} 4 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="ContextDone",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="WindowExceeded",shard_name="0"} 6 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Disabled",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastFailoverTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastReparentTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Shutdown",shard_name="0"} 0 +``` + +NOTE: Reviewing these results we can see value for `WindowExceeded` at 6; +informing us the `buffer_window` was not long enough for these request. + + + +### Scenario 7: Replica never becomes Primary + +There may be time in which the PRS event takes too long and must be rolled back. +To accomplish this scenario we will need to ensure we are using an older version +of MySQL, and we will need to send excessive traffic to vtgate. + +{{< warning >}} +This scenario assumes you are running Ubuntu LTS 20.04, you may have to adjust if +your environment is different. +{{< /warning >}} + + +Here we will tear down the cluster, install an older version of MySQL, and +rebuild: + +``` +Terminal 1: + Hit "Ctrl + C" to kill the vtgate process + + $ ./401_teardown.sh + $ rm -rf ./vtdataroot + + $ sudo apt-get install mysql-client-core-8.0=8.0.19-0ubuntu5 mysql-server-core-8.0=8.0.19-0ubuntu5 + + $ ./101_initial_cluster.sh + $ ps aux | grep [v]tgate + $ pkill vtgate + $ vtgate --topo_implementation etcd2 --topo_global_server_address localhost:2379 \ + --topo_global_root /vitess/global --log_dir ~/github/vitess/examples/local/vtdataroot/tmp \ + --log_queries_to_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate_querylog.txt \ + --port 15001 --grpc_port 15991 --mysql_server_port 15306 --mysql_server_socket_path /tmp/mysql.sock \ + --cell zone1 --cells_to_watch zone1 --tablet_types_to_wait PRIMARY,REPLICA \ + --service_map grpc-vtgateservice --pid_file ~/github/vitess/examples/local/vtdataroot/tmp/vtgate.pid \ + --mysql_auth_server_impl none --enable_buffer=1 +``` + +``` +Terminal 2: + Ctrl + C + (venv) $ gateslap examples/04_numerous_heavy_traffic.ini +``` + +As soon as the heavy traffic starts to generate send the PRS command. + +``` +Terminal 3: + $ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +``` + +#### Results: + +Here the buffering takes too long to complete, as a result the application +heavily utilizes error handling to recover. When programming for error handling +in these events, consider allowing the client enough time to recover from an +attempted RPC + rollback. This scenario will retry the connection 10 times, +waiting 5 seconds between each attempt. + +Part of the reason we had to downgrade MySQL was to make replication issues more +relevant. In this scenario vtgate bailed on the PlannedReparentShard as the +primary candidate `REPLICA` failed to catch up to the `PRIMARY`. + +``` +$ time vtctldclient --server localhost:15999 PlannedReparentShard commerce/0 +PlannedReparentShard Error: rpc error: code = Unknown desc = primary-elect tablet zone1-0000000101 failed +to catch up with replication MySQL56/4fb7c72c-62c8-11ec-8287-8cae4cdeeda4:1-1677: rpc error: code = Unknown +desc = TabletManager.WaitForPosition on zone1-0000000101 error: timed out waiting for position +4fb7c72c-62c8-11ec-8287-8cae4cdeeda4:1-1677: timed out waiting for position 4fb7c72c-62c8-11ec-8287-8cae4cdeeda4:1-1677 + +E1221 19:44:29.715359 203407 main.go:76] remote error: rpc error: code = Unknown desc = primary-elect tablet +zone1-0000000101 failed to catch up with replication MySQL56/4fb7c72c-62c8-11ec-8287-8cae4cdeeda4:1-1677: +rpc error: code = Unknown desc = TabletManager.WaitForPosition on zone1-0000000101 error: timed out waiting for position +4fb7c72c-62c8-11ec-8287-8cae4cdeeda4:1-1677: timed out waiting for position 4fb7c72c-62c8-11ec-8287-8cae4cdeeda4:1-1677 + +real 0m35.458s +user 0m0.015s +sys 0m0.005s + +``` + +There are a few things we can do to resolve this issue: + +* Upgrade the MySQL version +* Perform these operations during non-peak times +* Ensure we have error handling in case the PRS command fails +* Increase the buffer_window to buffer request instead of return errors + +This scenario was designed to show buffering assisting, even during a failed +PlannedReparentShard: + +```sh +curl -s localhost:15001/metrics | grep -v '^#' | grep buffer_requests +vtgate_buffer_requests_buffered{keyspace="commerce",shard_name="0"} 30 +vtgate_buffer_requests_buffered_dry_run{keyspace="commerce",shard_name="0"} 0 +vtgate_buffer_requests_drained{keyspace="commerce",shard_name="0"} 15 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="ContextDone",shard_name="0"} 0 +vtgate_buffer_requests_evicted{keyspace="commerce",reason="WindowExceeded",shard_name="0"} 15 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="BufferFull",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Disabled",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastFailoverTooRecent",shard_name="0"} 50 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="LastReparentTooRecent",shard_name="0"} 0 +vtgate_buffer_requests_skipped{keyspace="commerce",reason="Shutdown",shard_name="0"} 0 +``` + +NOTE: Reviewing the results, we can see from the `WindowExceeded` metric some of +the buffered queries expired. If this is common you may want to increase your +`buffer_window` to cover these failures. Retrying this scenario with the following +vtgate flags appended resolves many of these errors: + +`--buffer_max_failover_duration=1m --buffer_min_time_between_failovers=2m --buffer_window=60s` + +## Revert your configurations + +To undo our configuration we will need to tear the cluster down; upgrade MySQL; +then rebuild the vitess cluster: + +``` +Terminal 1: + Ctrl + C + + $ ./401_teardown.sh + $ rm -rf ./vtdataroot + + $ sudo apt-get upgrade && sudo apt-get update + +``` diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/comment-directives.md b/content/en/docs/19.0/user-guides/configuration-advanced/comment-directives.md new file mode 100644 index 000000000..bc7b06478 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/comment-directives.md @@ -0,0 +1,121 @@ +--- +title: Comment Directives +weight: 35 +--- + +Vitess supports a small set of meta-directives that can be passed from the application to Vitess as SQL comments in the application. These directives can be used to alter the behavior of Vitess on a per-query basis. This is often used by advanced Vitess users to obtain finely granular control over the behavior of Vitess, often for the purposes of optimizing performance. + +All the comment directives, included as part of the query, take the form: + +```sh +/*vt+ comment_directive_name_plus_argument */ +``` + +One thing to note when experimenting with query comments is that various MySQL clients can strip comments by default before sending the query to the server. You will need to make sure your query comments are not being stripped. For example, the MySQL CLI (`mysql`) will do this unless you pass it the -c (or --comments) parameter. + +## Query timeouts (`QUERY_TIMEOUT_MS`) + +In Vitess, individual non-streaming queries are subject to query timeouts. This are typically set by the vttablet option `--queryserver-config-query-timeout`. Whole transactions are also subject to the vttablet timeout setting `--queryserver-config-transaction-timeout`. + +However, for read (`SELECT`) queries, it is also possible to use a special Vitess query comment format to set a lower timeout for certain queries, e.g.: + +```sh +mysql> select /*vt+ QUERY_TIMEOUT_MS=1 */ sleep(1); +ERROR 1317 (70100): target: keyspace1.0.primary: vttablet: rpc error: code = DeadlineExceeded desc = context deadline exceeded +``` + +As indicated by the comment name (QUERY_TIMEOUT_MS), this timeout is in milliseconds. + +### Limitation and caveats: + +- Only works for `SELECT` (read) queries. +- Does not work when doing manual shard-targeting. See [this issue](https://github.com/vitessio/vitess/issues/7031). +- Cannot set a higher limit to evade the settings for `--queryserver-config-query-timeout` and/or `--queryserver-config-transaction-timeout`. + +## Multi-shard Autocommit (`MULTI_SHARD_AUTOCOMMIT`) + +Using this in, for example, an insert statement will cause individual shard autocommit to be used for the shards where the rows for the insert are routed. This means that if one of the individual shard inserts fails, it will not be possible to roll back the inserts on all the other shards. This is the default behavior. A helpful way to think of this is as best-effort cross-shard writes, with the application being responsible for repairs in the case of errors. For an example, read our [Shard Isolation and Atomicity guide](../../configuration-advanced/shard-isolation-atomicity/#method-1--the-naive-way). + +## Skip query plan cache (`SKIP_QUERY_PLAN_CACHE`) + +Vitess maintains a query/plan cache in both `vtgate` and `vttablet`. These caches serve different purposes: + +- `vtgate`: overall targeting of queries against backend shard tablets +- `vttablet`: shard-specific details like field definitions/types, etc. + +The `SKIP_QUERY_PLAN_CACHE` comment directive tells `vttablet` to skip caching this query in its query cache. This can be used by a Vitess-aware application to avoid polluting the cache with things like bulk insert plans, etc. + +Since vttablet places a memory size limit on the query cache, it is much less likely for this cache to get overrun by queries like bulk inserts. As a result, it should be less necessary to use this comment directive, other than as a performance optimization. Previously, it was unbounded in memory, or in other words it was only bounded by number of entries. At that point it might have been necessary to use to avoid vttablet out-of-memory (OOM) situations. + +## Scatter errors as warnings (`SCATTER_ERRORS_AS_WARNINGS`) + +Vitess will, by default, return only an error if any of the shards involved in a scatter query reports an error. This is important for strong correctness, however, in some cases it may be necessary or desirable to have Vitess return partial results from the available shards anyway. The application can then act accordingly based on the results. + +The `SCATTER_ERRORS_AS_WARNINGS` comment directive enables exactly this, by returning the partial results from the healthy shards in the scatter query, and returning the error(s) from the unhealthy shard(s) as warnings. The application can then potentially use the warning information to guide its subsequent action. + +## Ignore max payload size (`IGNORE_MAX_PAYLOAD_SIZE`) + +By default, Vitess will try to handle queries of any size. It is possible to use the `vtgate` parameter `--max_payload_size` (default unlimited) to limit the size of an incoming query to a certain number of bytes. Queries larger than this limit will then be rejected by `vtgate`. + +The `IGNORE_MAX_PAYLOAD_SIZE` comment directive allows a Vitess-aware application to bypass this limit, essentially setting it to the default of unlimited for that query. + +## Ignore max memory rows (`IGNORE_MAX_MEMORY_ROWS`) + +By default, `vtgate` will allow intermediate results for things like in-vtgate sorting and joining, up to a maximum of number of rows per query. This is to avoid using massive amounts of memory in `vtgate`. This limit is set using the `vtgate` parameter `--max_memory_rows`, which defaults to 300,000. Note that this limit is not a direct memory usage limit, since 300,000 very large rows could still be a huge amount of memory. + +The `IGNORE_MAX_MEMORY_ROWS` comment directive allows a Vitess-aware application to bypass this limit, essentially setting it to an unlimited number of rows for that query. Since this override can result in very large, and even potentially effectively unbounded, amounts of memory being used by `vtgate`, it should be used with extreme caution. + +## Allow scatter (`ALLOW_SCATTER`) + +In Vitess, it is possible to use the `vtgate` parameter `--no_scatter` to prevent `vtgate` from issuing scatter queries. Thus only queries that do not scatter will be allowed. + +This comment directive is used to override that limitation, allowing application code to be customized to allow scatters for certain chosen use-cases, but not for the general case. + +## Consolidator (`CONSOLIDATOR`) + +In `vttablet`, the consolidator is enabled with the `--enable_consolidator` and `--enable_consolidator_replicas` flags. Those settings may be overridden with this comment directive, allowing application code to opt into (or out of) consolidation for individual `SELECT` queries. + +This directive requires one of the following values: + + * `disabled` + * `enabled` + * `enabled_replicas` + +### Planner (`PLANNER`) + +Overrides the default planner to the one specified by the directive. Example query: + +```sql +select /*vt+ PLANNER=gen4 */ * from user; +``` + +Valid values are the same as for the planner flag - `Gen4`, `Gen4Greedy` and `Gen4Left2Right`. + +### Workload name (`WORKLOAD_NAME`) + +Specifies the client application workload name. This does not affect query execution, but can be used to instrument +some `vttablet` metrics to include a label specifying the workload name. It can be useful if you are interested in +getting insights about how much of the work being done at the `vttablet` level is being caused by each client +application workload. For this to work, you must use `--enable-per-workload-table-metrics` at the `vttablet`, and pass +the client workload name on each query as a directive. For example: + +```sql +select /*vt+ WORKLOAD_NAME=webstore */ * from commerce.customer; +``` + +will result in metrics such as this one: + +```bash +% curl -s localhost:15100/metrics | grep "table=\"customer\"" |grep webstore +vttablet_query_counts{plan="Select",table="customer",workload="webstore"} 1 +vttablet_query_error_counts{plan="Select",table="customer",workload="webstore"} 0 +vttablet_query_rows_returned{plan="Select",table="customer",workload="webstore"} 0 +vttablet_query_times_ns{plan="Select",table="customer",workload="webstore"} 602557 +``` + +As shown above, the metrics being instrumented this way are `vttablet_query_counts`, `vttablet_query_error_counts`, +`vttablet_query_rows_returned` and `vttablet_query_times_ns`. + +If the query lacks the `WORKLOAD_NAME` directive, the corresponding label in the metric will have the value of an empty +string. If `vttablet` is not started with `--enable-per-workload-table-metrics`, metrics are emitted without the +workload label (e.g. `vttablet_query_counts{plan="Select",table="customer"}`. 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 new file mode 100644 index 000000000..9418102c8 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/createlookupvindex.md @@ -0,0 +1,751 @@ +--- +title: CreateLookupVindex +weight: 30 +aliases: ['/docs/user-guides/createlookupvindex/'] +--- + +{{< info >}} +This guide follows on from the Get Started guides. Please make sure that you have +an [Operator](../../../get-started/operator) or [local](../../../get-started/local) installation ready. Make sure you +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 +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. + +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 ``: + +```bash +$ mysql -P 15306 -h 127.0.0.1 -u root --binary-as-hex=false -A +Welcome to the MySQL monitor. Commands end with ; or \g. +... +``` + +```mysql +mysql> use customer; +Database changed + +mysql> show tables; ++-----------------------+ +| Tables_in_vt_customer | ++-----------------------+ +| corder | +| customer | ++-----------------------+ +2 rows in set (0.00 sec) + +mysql> desc corder; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| order_id | bigint | NO | PRI | NULL | | +| customer_id | bigint | YES | | NULL | | +| sku | varbinary(128) | YES | | NULL | | +| price | bigint | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +4 rows in set (0.01 sec) + +mysql> insert into corder (order_id, customer_id, sku, price) values (1, 1, "Product_1", 100); +Query OK, 1 row affected (0.01 sec) + +mysql> insert into corder (order_id, customer_id, sku, price) values (2, 1, "Product_2", 101); +Query OK, 1 row affected (0.01 sec) + +mysql> insert into corder (order_id, customer_id, sku, price) values (3, 2, "Product_3", 102); +Query OK, 1 row affected (0.01 sec) + +mysql> insert into corder (order_id, customer_id, sku, price) values (4, 3, "Product_4", 103); +Query OK, 1 row affected (0.01 sec) + +mysql> insert into corder (order_id, customer_id, sku, price) values (5, 4, "Product_5", 104); +Query OK, 1 row affected (0.03 sec) + +mysql> select * from corder; ++----------+-------------+-----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+-----------+-------+ +| 1 | 1 | Product_1 | 100 | +| 2 | 1 | Product_2 | 101 | +| 3 | 2 | Product_3 | 102 | +| 4 | 3 | Product_4 | 103 | +| 5 | 4 | Product_5 | 104 | ++----------+-------------+-----------+-------+ +5 rows in set (0.01 sec) +``` + +
    + +If we look at the [VSchema](../../../reference/features/vschema/) for the +`customer.corder` table, we will see there is a `hash` index on the +`customer_id` column: + +```json +$ vtctldclient GetVSchema customer +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash", + "params": {}, + "owner": "" + } + }, + "tables": { + "corder": { + "type": "", + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash", + "columns": [] + } + ], + "auto_increment": { + "column": "order_id", + "sequence": "order_seq" + }, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "customer": { + "type": "", + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash", + "columns": [] + } + ], + "auto_increment": { + "column": "customer_id", + "sequence": "customer_seq" + }, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + } + }, + "require_explicit_routing": false +} +``` + +
    + +We can now see that 4 of our 5 rows have ended up on the `-80` shard with the +5th row on the `80-` shard: + +```sql +mysql> use customer/-80 +Database changed + +mysql> select * from corder; ++----------+-------------+-----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+-----------+-------+ +| 1 | 1 | Product_1 | 100 | +| 2 | 1 | Product_2 | 101 | +| 3 | 2 | Product_3 | 102 | +| 4 | 3 | Product_4 | 103 | ++----------+-------------+-----------+-------+ +4 rows in set (0.00 sec) + +mysql> use customer/80- +Database changed + +mysql> select * from corder; ++----------+-------------+-----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+-----------+-------+ +| 5 | 4 | Product_5 | 104 | ++----------+-------------+-----------+-------+ +1 row in set (0.01 sec) +``` + +
    + +Note that this skewed distribution is completely coincidental — for larger +numbers of rows we would expect the distribution to be approximately even +for a `hash` index. + +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: + +```bash +$ vtctlclient --server localhost:15999 CreateLookupVindex -- --tablet_types=RDONLY customer "$(cat lookup_vindex.json)" +``` + +
    + +Note: + +* We are specifying a tablet_type of `RDONLY`; meaning it is going to + run the VReplication streams from tablets of the `RDONLY` type **only**. + If tablets of this type cannot be found, in a shard, the lookup Vindex + population will fail. + +Now, in our case, the table is tiny, so the copy will be instant, but +in a real-world case this might take hours. To monitor the process, +we can use the usual VReplication commands. However, the VReplication +status commands needs to operate on individual tablets. Let's check +which tablets we have in our environment, so we know which tablets to +issue commands against: + +```bash +$ vtctldclient --server localhost:15999 GetTablets --keyspace customer +zone1-0000000300 customer -80 primary localhost:15300 localhost:17300 [] 2020-08-13T01:23:15Z +zone1-0000000301 customer -80 replica localhost:15301 localhost:17301 [] +zone1-0000000302 customer -80 rdonly localhost:15302 localhost:17302 [] +zone1-0000000400 customer 80- primary localhost:15400 localhost:17400 [] 2020-08-13T01:23:15Z +zone1-0000000401 customer 80- replica localhost:15401 localhost:17401 [] +zone1-0000000402 customer 80- rdonly localhost:15402 localhost:17402 [] +``` + +
    + +Now we can look what happened in greater detail: + +* VReplication streams were setup from the primary tablets + `zone1-0000000300` and `zone1-0000000400`; pulling data from the `RDONLY` + source tablets `zone1-0000000302` and `zone1-0000000402`. +* 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. + +{{< info >}} +The created vreplication workflow will have a generated name of `_vdx`. +So in our example here: `corder_lookup_vdx`. +{{< /info >}} + +```json +$ vtctlclient --server localhost:15999 Workflow customer.corder_lookup_vdx show +{ + "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": "" +} +``` + +
    + +There is a lot going on in this output, but the most important parts are the +`state` and `message` fields which say `Stopped` and `Stopped after copy.` +for all four of the streams. This means that the VReplication streams finished +their copying/backfill of the lookup table. + +Note that if the tables were large and the copy was still in progress, the +`state` field would say `Copying` — you can see the state/progress as part +of `Workflow show` json output. + +We can verify the result of the backfill by looking at the `customer` +keyspace again in the MySQL client: + +```sql +mysql> show tables; ++-----------------------+ +| Tables_in_vt_customer | ++-----------------------+ +| corder | +| corder_lookup | +| customer | ++-----------------------+ +3 rows in set (0.01 sec) +``` + +
    + +Note there is now a new table, `corder_lookup`; which was created as the +backing table for the lookup Vindex. Lets look at this table: + +```sql +mysql> desc corder_lookup; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| sku | varbinary(128) | NO | PRI | NULL | | +| keyspace_id | varbinary(128) | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +2 rows in set (0.01 sec) + +mysql> select sku, hex(keyspace_id) from corder_lookup; ++-----------+------------------+ +| sku | hex(keyspace_id) | ++-----------+------------------+ +| Product_2 | 166B40B44ABA4BD6 | +| Product_3 | 06E7EA22CE92708F | +| Product_1 | 166B40B44ABA4BD6 | +| Product_4 | 4EB190C9A2FA169C | +| Product_5 | D2FD8867D50D2DFE | ++-----------+------------------+ +``` + +
    + +Basically, this shows exactly what we expected. Now, we have to clean-up +the artifacts of the backfill. The `ExternalizeVindex` command will delete +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 +``` + +
    + +Next, to confirm the lookup Vindex is doing what we think it should, we can +use the [`vexplain plan` SQL statement](../../sql/vexplain/): + +```sql +mysql> vexplain plan select * from corder where customer_id = 1; ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| JSON | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| { + "OperatorType": "Route", + "Variant": "EqualUnique", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select order_id, customer_id, sku, price from corder where 1 != 1", + "Query": "select order_id, customer_id, sku, price from corder where customer_id = 1", + "Table": "corder", + "Values": [ + "INT64(1)" + ], + "Vindex": "hash" +} | ++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +
    + +Since the above `select` statement is doing a lookup using the primary Vindex +on the `corder` table, this query does not Scatter (variant is +`SelectEqualUnique`), as expected. Let's try a scatter query to see what that +looks like: + +```sql +mysql> vexplain select * from corder; ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| JSON | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| { + "OperatorType": "Route", + "Variant": "Scatter", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select order_id, customer_id, sku, price from corder where 1 != 1", + "Query": "select order_id, customer_id, sku, price from corder", + "Table": "corder" +} | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +So now we see the expectied variant of `SelectScatter` for a scatter query. +Let's try a lookup on a column that does *not* have a primary or secondary +(lookup) Vindex, e.g. the `price` column: + +```sql +mysql> vexplain select * from corder where price = 103\G +*************************** 1. row *************************** +JSON: { + "OperatorType": "Route", + "Variant": "Scatter", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select order_id, customer_id, sku, price from corder where 1 != 1", + "Query": "select order_id, customer_id, sku, price from corder where price = 103", + "Table": "corder" +} +1 row in set (0.00 sec) +``` + +That also scatters, as expected, because there's no Vindex on the column. + +Now, let's try a lookup on the `sku` column, which we have created our lookup +Vindex on: + +```sql +mysql> vexplain select * from corder where sku = "Product_1"; ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| JSON | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| { + "OperatorType": "VindexLookup", + "Variant": "EqualUnique", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "Values": [ + "VARCHAR(\"Product_1\")" + ], + "Vindex": "corder_lookup", + "Inputs": [ + { + "OperatorType": "Route", + "Variant": "IN", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select sku, keyspace_id from corder_lookup where 1 != 1", + "Query": "select sku, keyspace_id from corder_lookup where sku in ::__vals", + "Table": "corder_lookup", + "Values": [ + ":sku" + ], + "Vindex": "binary_md5" + }, + { + "OperatorType": "Route", + "Variant": "ByDestination", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select order_id, customer_id, sku, price from corder where 1 != 1", + "Query": "select order_id, customer_id, sku, price from corder where sku = 'Product_1'", + "Table": "corder" + } + ] +} | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +
    + +As expected, we can see it is not scattering anymore, which it would have +before we executed the `CreateLookupVindex` command. + +Lastly, let's ensure that the lookup Vindex is being updated appropriately +when we insert and delete rows: + +```sql +mysql> select * from corder; ++----------+-------------+-----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+-----------+-------+ +| 5 | 4 | Product_5 | 104 | +| 1 | 1 | Product_1 | 100 | +| 2 | 1 | Product_2 | 101 | +| 3 | 2 | Product_3 | 102 | +| 4 | 3 | Product_4 | 103 | ++----------+-------------+-----------+-------+ +5 rows in set (0.00 sec) + +mysql> delete from corder where customer_id = 1 and sku = "Product_1"; +Query OK, 1 row affected (0.03 sec) + +mysql> select * from corder; ++----------+-------------+-----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+-----------+-------+ +| 2 | 1 | Product_2 | 101 | +| 3 | 2 | Product_3 | 102 | +| 4 | 3 | Product_4 | 103 | +| 5 | 4 | Product_5 | 104 | ++----------+-------------+-----------+-------+ +4 rows in set (0.01 sec) + +mysql> select sku, hex(keyspace_id) from corder_lookup; ++-----------+------------------+ +| sku | hex(keyspace_id) | ++-----------+------------------+ +| Product_4 | 4EB190C9A2FA169C | +| Product_5 | D2FD8867D50D2DFE | +| Product_2 | 166B40B44ABA4BD6 | +| Product_3 | 06E7EA22CE92708F | ++-----------+------------------+ +4 rows in set (0.01 sec) +``` + +
    + +We deleted a row from the `corder` table, and the matching lookup Vindex row +is gone. Now we can try adding a row: + +```sql +mysql> insert into corder (order_id, customer_id, sku, price) values (6, 1, "Product_6", 105); +Query OK, 1 row affected (0.02 sec) + +mysql> select * from corder; ++----------+-------------+-----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+-----------+-------+ +| 2 | 1 | Product_2 | 101 | +| 3 | 2 | Product_3 | 102 | +| 4 | 3 | Product_4 | 103 | +| 6 | 1 | Product_6 | 105 | +| 5 | 4 | Product_5 | 104 | ++----------+-------------+-----------+-------+ +5 rows in set (0.00 sec) + +mysql> select sku, hex(keyspace_id) from corder_lookup; ++-----------+------------------+ +| sku | hex(keyspace_id) | ++-----------+------------------+ +| Product_4 | 4EB190C9A2FA169C | +| Product_5 | D2FD8867D50D2DFE | +| Product_6 | 166B40B44ABA4BD6 | +| Product_2 | 166B40B44ABA4BD6 | +| Product_3 | 06E7EA22CE92708F | ++-----------+------------------+ +5 rows in set (0.00 sec) +``` + +
    + +We added a new row to the `corder` table, and now we have a new row in the +lookup table! diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/integration-with-orchestrator.md b/content/en/docs/19.0/user-guides/configuration-advanced/integration-with-orchestrator.md new file mode 100644 index 000000000..cc912a965 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/integration-with-orchestrator.md @@ -0,0 +1,7 @@ +--- +title: Integration with Orchestrator +weight: 100 +aliases: ['/docs/user-guides/integration-with-orchestrator/'] +--- + +Orchestrator integration has been removed. Please use [VTOrc](../../configuration-basic/vtorc) instead. diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/ldap_auth.md b/content/en/docs/19.0/user-guides/configuration-advanced/ldap_auth.md new file mode 100644 index 000000000..ed51f2ae1 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/ldap_auth.md @@ -0,0 +1,80 @@ +--- +title: LDAP authentication +weight: 3 +aliases: ['/docs/user-guides/ldap_auth/'] +--- + +Currently, Vitess supports two ways to authenticate to `vtgate` via the MySQL protocol: + + * **Static** : You provide a static configuration file to `vtgate` with user names and plaintext passwords or `mysql_native_password` password hashes. This file can be reloaded without restarting `vtgate`. Further details can be found [here](../user-management). + * **LDAP** : You provide the necessary details of an upstream LDAP server, along with credentials and configuration, to query it. Using this information, the LDAP passwords for a user can then be used to authenticate the same user against `vtgate`. You can also integrate with LDAP groups to allow ACLs to be managed using information from the LDAP server. + +In this guide, we will examine the capabilities of the `vtgate` LDAP integration and how to configure them. + +## Requirements + +There are a few requirements that are necessary for the `vtgate` LDAP integration to work: + + * The communication between `vtgate` and the LDAP server has to be encrypted. + * Encrypted communication to LDAP has to be via LDAP over TLS (STARTTLS) and not via LDAP over SSL (LDAPS). The latter is not a standardized protocol and is not supported by Vitess. Ensure that your LDAP server and the LDAP URI (hostname/port) that you provide supports STARTTLS. + * The application MySQL protocol connections to `vtgate` that use LDAP usernames/passwords need to use TLS. This is required because of the next point, but can be bypassed. We strongly **DO NOT** recommend doing this. + * The application needs to be able to, and configured to, pass its password authentication using the cleartext MySQL authentication protocol. This is why it is required that the MySQL connection to `vtgate` be encrypted first. This is required because LDAP servers do not standardize their password hashes and, as a result, a cleartext password is required by `vtgate` to bind (i.e. authenticate) against the LDAP server to verify the user's password. Note that some applications might not support passing cleartext MySQL passwords without alteration or configuration. An example is recent versions of the MySQL CLI client `mysql` need the additional `--enable-cleartext-plugin` option to allow the passing of cleartext passwords. + +## Configuration + +To configure `vtgate` to integrate with LDAP you will have to perform various tasks: + + * Generate/obtain TLS certificate(s) for the `vtgate` server(s), and configure `vtgate` to use them. Further details can be found [here](https://github.com/aquarapid/vitess_examples/blob/master/tls/securing_vitess.md). + * Obtain or add the necessary LDAP user/groups for integration with `vtgate`. In general, you will need: + * LDAP user entries for each of the MySQL users you want to use at the `vtgate` level. An example might be a readonly user, a readwrite user, and an admin/DBA user. + * Ensure these users are part of one or more LDAP groups. This is not strictly required by Vitess, but is leveraged to obtain group membership that can then be used in Vitess (`vttablet`)[ACLs](../authorization). At the moment if you use an LDAP user that is not a member of an LDAP group, the MySQL client authentication to `vtgate` will fail, even if the password is correct. + * As mentioned above, you also need to have: + * Your LDAP server setup for STARTTLS + * Obtained the LDAP URI to connect to the LDAP server + * The CA certificate, that your LDAP server TLS certificate is signed by, in PEM format + * Make sure that you are accessing the LDAP server via a hostname or IP SAN that is defined in your LDAP server TLS certificate. If not, you will not be able to use your LDAP server as-is from `vtgate`. + +Once you have your prerequisites above ready, you can now construct your JSON configuration file for `vtgate` using the command line parameter `--mysql_ldap_auth_config_file`. The content of this file is a JSON format object with string key/value members as follows: + +```shell +{ + "LdapServer": "ldapserver.example.org:389", + "LdapCert": "path/to/ldap-client-cert.pem", + "LdapKey": "path/to/ldap-client-key.pem", + "LdapCA": "path/to/ldap-server-ca.pem", + "User": "cn=admin,dc=example,dc=org", + "Password": "adminpassword!", + "GroupQuery": "ou=groups,ou=people,dc=example,dc=org", + "UserDnPattern": "uid=%s,ou=users,ou=people,dc=example,dc=org", + "RefreshSeconds": 300 +} +``` + +Not all these options are necessary in all configurations. Here are what each key/value option represents: + + * **LdapServer** : Hostname/IP and port to access the LDAP server via using [STARTTLS](https://www.digitalocean.com/community/tutorials/how-to-encrypt-openldap-connections-using-starttls). Note that as mentioned above, this needs to match the server TLS certificate presented by the LDAP server. This is required. + * **LdapCert** : Path to the local file that contains the PEM format TLS client certificate that you want to present to the LDAP server. This is optional unless you use client-certificates with the LDAP server. If you are using this option, `LdapKey` is also required. + * **LdapKey** : Path to the local file that contains the PEM format TLS private key for the client certificate you want to present to the LDAP server. This is optional unless you use client-certificates with the LDAP server. If you are using this option, `LdapCert` is also required. + * **LdapCA** : Path to the local file that contains the PEM format TLS CA certificate to verify against the TLS server certificate presented by the LDAP server. This is required. + * **User** : DN of the LDAP user you will be authenticating to the LDAP server to read information such as group membership. Required, unless you are using LDAP client certificates to authenticate to the LDAP server. If you are using this option, `Password` option is also required. + * **Password** : Cleartext password for the LDAP user specified above in `User`. This is required, unless you are using LDAP client certificates to authenticate to the LDAP server. If you are using this option, `User` option is also required. + * **GroupQuery** : LDAP base DN from which to start the group membership query to establish the group of which the `User` specified (or implied via the client certificate) is a member. The group membership query itself is hardcoded to the LDAP query filter of `(memberUid=%s)` where `%s` is the authenticating username. This is required. + * **UserDnPattern** : LDAP DN pattern to autofill with MySQL username passed during MySQL client authentication to `vtgate`. This DN is then used, along with the password provided to `vtgate`, to attempt to bind with the LDAP server. If the bind is successful, you know that the password provided to `vtgate` was valid. This is required. + * **RefreshSeconds** : Number of seconds that you should cache individual LDAP credentials for in-memory at the `vtgate`. This is used to reduce load on the LDAP for high traffic MySQL servers. As well as to avoid short LDAP server outages from causing Vitess/`vtgate` authentication outages. Default value is 0, which means **do not cache**. For production it is recommended to set this value to something reasonably high, for example at least a few minutes. This is optional. + +Note that `vtgate` only does very basic validation of the values passed here and that incorrect configurations may just fail at runtime. If you are lucky, relevant errors may be logged by `vtgate`, but in many cases incorrect configuration will just result in a `vtgate` instance that you cannot log into via the MySQL protocol. + +For debugging this, it is useful to have access to the logs from your LDAP server that you are pointing to. The logs would preferably be at trace or debug level, so that you can see each LDAP bind and search operation against the LDAP server as you are testing. + +Once you have constructed the above file, you will need to remove any options that references static authentication from your `vtgate` command line such as: + + * `--mysql_auth_server_static_file` + * `--mysql_auth_server_static_string` + * `--mysql_auth_static_reload_interval` + * `--mysql_auth_server_impl static` + +and add the following new options: + +```shell +--mysql_auth_server_impl ldap --mysql_ldap_auth_config_file /path/to/ldapconfig.json +``` diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/query-consolidation.md b/content/en/docs/19.0/user-guides/configuration-advanced/query-consolidation.md new file mode 100644 index 000000000..9c59f9b93 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/query-consolidation.md @@ -0,0 +1,27 @@ +--- +title: Query Consolidation +weight: 50 +aliases: [] +--- +Query consolidation is a VTTablet feature meant to protect your database from an overload caused by a spike in QPS for a specific query. + +Without this feature enabled such spikes can completely overwhelm the database. With this feature enabled the following will occur: when a vttablet receives a query, if an identical query is already in the process of being executed, the query will then wait. +As soon as the first query returns from the underlying database, the result is sent to all callers that have been waiting. + +**Note**: an identical query is one that is exactly the same, including literals and bind variables. + +Flags: + +* `--enable_consolidator`: Defaults to true. +* `--enable_consolidator_replicas`: Only enable query consolidation on non-primary tablets. + +## Consistency + +It is important to note that in some cases read-after-write consistency can be lost. + +For example, if user1 issues a read query and user2 issues a write, that changes the result that the first read query would get, then user2 issues an identical read while user1's read is still executing. + +In this case the consolidator will kick in and user2 will get the result of user1's query thereby losing read-after-write consistency. + +If the application is sensitive to this behavior then you can specify that consolidation should be disabled on the primary using the following flags: `--enable_consolidator=false` and `--enable_consolidator_replicas=true` + 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 new file mode 100644 index 000000000..423dc2588 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/region-sharding.md @@ -0,0 +1,539 @@ +--- +title: Region Based Sharding +weight: 25 +aliases: ['/docs/user-guides/region-sharding/'] +--- + +{{< info >}} +This guide follows on from the Get Started guides. Please make sure that you have a [local](../../../get-started/local) installation ready. You should also have already gone through the [MoveTables](../../migration/move-tables) and [Resharding](../../configuration-advanced/resharding) tutorials. The commands in this guide also assume you have setup the shell aliases from this example contained in `env.sh`. +{{< /info >}} + +## Introduction + +Having gone through the [Resharding tutorial](../resharding/), you should be familiar with +[VSchema](../../../reference/features/vschema) and [Vindexes](../../../reference/features/vindexes). +In this tutorial, we will perform resharding on an existing keyspace using a location-based vindex. We will create 4 shards: `-40`, `40-80`, `80-c0`, `c0-`. The location will be denoted by a `country` column in the customer table. + +## Create and Start the Cluster + +Start by copying the [`region_sharding` examples](https://github.com/vitessio/vitess/tree/main/examples/region_sharding) +included with Vitess to your preferred location and running the `101_initial_cluster.sh` script: + +```bash +cp -r /examples ~/my-vitess-example/examples +cp -r /web ~/my-vitess-example +cd ~/my-vitess-example/examples/region_sharding +./101_initial_cluster.sh +``` + +## Initial Schema + +This 101 script created the `customer` table in the unsharded `main` keyspace. This is the table that we will be +sharding by country. + +We can connect to our new cluster — using the `mysql` alias setup by `env.sh` within the script — to confirm our current schema: + +```mysql +$ mysql --binary-as-hex=false +... + +mysql> show databases; ++--------------------+ +| Database | ++--------------------+ +| main | +| information_schema | +| mysql | +| sys | +| performance_schema | ++--------------------+ +5 rows in set (0.00 sec) + +mysql> use customer; +Database changed + +mysql> show tables; ++----------------+ +| Tables_in_main | ++----------------+ +| customer | ++----------------+ +1 row in set (0.00 sec) + +mysql> show create table customer\G +*************************** 1. row *************************** + Table: customer +Create Table: CREATE TABLE `customer` ( + `id` int NOT NULL, + `fullname` varbinary(256) DEFAULT NULL, + `nationalid` varbinary(256) DEFAULT NULL, + `country` varbinary(256) DEFAULT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci +1 row in set (0.00 sec) +``` + +## Creating Test Data + +Let's now create some test data: + +```bash +$ mysql < ./insert_customers.sql + +$ mysql --table < ./show_initial_data.sql ++----+------------------+-------------+---------------+ +| id | fullname | nationalid | country | ++----+------------------+-------------+---------------+ +| 1 | Philip Roth | 123-456-789 | United States | +| 2 | Gary Shteyngart | 234-567-891 | United States | +| 3 | Margaret Atwood | 345-678-912 | Canada | +| 4 | Alice Munro | 456-789-123 | Canada | +| 5 | Albert Camus | 912-345-678 | France | +| 6 | Colette | 102-345-678 | France | +| 7 | Hermann Hesse | 304-567-891 | Germany | +| 8 | Cornelia Funke | 203-456-789 | Germany | +| 9 | Cixin Liu | 789-123-456 | China | +| 10 | Jian Ma | 891-234-567 | China | +| 11 | Haruki Murakami | 405-678-912 | Japan | +| 12 | Banana Yoshimoto | 506-789-123 | Japan | +| 13 | Arundhati Roy | 567-891-234 | India | +| 14 | Shashi Tharoor | 678-912-345 | India | +| 15 | Andrea Hirata | 607-891-234 | Indonesia | +| 16 | Ayu Utami | 708-912-345 | Indonesia | ++----+------------------+-------------+---------------+ +``` + +## Prepare For Resharding + +Now that we have some data in our unsharded `main` keyspace, let's go ahead and perform the setup needed +for resharding. The initial vschema is unsharded and simply lists the customer table: + +```json +$ vtctldclient GetVSchema main +{ + "sharded": false, + "vindexes": {}, + "tables": { + "customer": { + "type": "", + "column_vindexes": [], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + } + }, + "require_explicit_routing": false +} +``` + +
    + +We are next going to prepare for having a sharded vschema in the cluster by editing the +`main_vschema_sharded.json` file and updating the the `region_map` key's value to point to the +filesystem path where that file resides on your machine. For example (relative paths are OK): + +```json + "region_map": "./countries.json", +``` + +
    + +We then run the 201 script: + +```bash +./201_main_sharded.sh +``` + +
    + +That script creates our sharded vschema as defined in the `main_vschema_sharded.json` file and it +creates a [lookup vindex](../../../reference/features/vindexes/#functional-and-lookup-vindex) using the +[`CreateLookupVindex` command](../../migration/move-tables/) with the definition found in the +`lookup_vindex.json` file. + +That file is where we both define the [lookup vindex](../../../reference/features/vindexes/#functional-and-lookup-vindex) +and associate it with the `customer` table in the `main` keyspace: + +```json +$ cat ./lookup_vindex.json +{ + "sharded": true, + "vindexes": { + "customer_region_lookup": { + "type": "consistent_lookup_unique", + "params": { + "table": "main.customer_lookup", + "from": "id", + "to": "keyspace_id" + }, + "owner": "customer" + } + }, + "tables": { + "customer": { + "column_vindexes": [ + { + "column": "id", + "name": "customer_region_lookup" + } + ] + } + } +} +``` + +
    + +Now if we look at the `main` keyspace's vschema again we can see that it now includes the `region_vdx` vindex and +a lookup vindex called `customer_region_lookup`: + +```json +$ vtctldclient GetVSchema main +{ + "sharded": true, + "vindexes": { + "customer_region_lookup": { + "type": "consistent_lookup_unique", + "params": { + "from": "id", + "table": "main.customer_lookup", + "to": "keyspace_id" + }, + "owner": "customer" + }, + "hash": { + "type": "hash", + "params": {}, + "owner": "" + }, + "region_vdx": { + "type": "region_json", + "params": { + "region_bytes": "1", + "region_map": "./countries.json" + }, + "owner": "" + } + }, + "tables": { + "customer": { + "type": "", + "column_vindexes": [ + { + "column": "", + "name": "region_vdx", + "columns": [ + "id", + "country" + ] + }, + { + "column": "id", + "name": "customer_region_lookup", + "columns": [] + } + ], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + }, + "customer_lookup": { + "type": "", + "column_vindexes": [ + { + "column": "id", + "name": "hash", + "columns": [] + } + ], + "auto_increment": null, + "columns": [], + "pinned": "", + "column_list_authoritative": false, + "source": "" + } + }, + "require_explicit_routing": false +} +``` + +
    + +Notice that the vschema shows a `hash` [vindex type](../../../reference/features/vindexes/#predefined-vindexes) for +the lookup table. This is automatically created by the `CreateLookupVindex` workflow, along with the +backing table needed to hold the vindex and populating it with the correct rows (for additional details on this +command see [the associated user-guide](../createlookupvindex/)). We can see that by checking our `main` +database/keyspace again: + +```mysql +mysql> show tables; ++-------------------+ +| Tables_in_vt_main | ++-------------------+ +| customer | +| customer_lookup | ++-------------------+ +2 rows in set (0.00 sec) + +mysql> describe customer_lookup; ++-------------+----------------+------+-----+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++-------------+----------------+------+-----+---------+-------+ +| id | int(11) | NO | PRI | NULL | | +| keyspace_id | varbinary(128) | YES | | NULL | | ++-------------+----------------+------+-----+---------+-------+ +2 rows in set (0.01 sec) + +mysql> select id, hex(keyspace_id) from customer_lookup; ++----+--------------------+ +| id | hex(keyspace_id) | ++----+--------------------+ +| 1 | 01166B40B44ABA4BD6 | +| 2 | 0106E7EA22CE92708F | +| 3 | 024EB190C9A2FA169C | +| 4 | 02D2FD8867D50D2DFE | +| 5 | 4070BB023C810CA87A | +| 6 | 40F098480AC4C4BE71 | +| 7 | 41FB8BAAAD918119B8 | +| 8 | 41CC083F1E6D9E85F6 | +| 9 | 80692BB9BF752B0F58 | +| 10 | 80594764E1A2B2D98E | +| 11 | 81AEFC44491CFE474C | +| 12 | 81D3748269B7058A0E | +| 13 | C062DCE203C602F358 | +| 14 | C0ACBFDA0D70613FC4 | +| 15 | C16A8B56ED414942B8 | +| 16 | C15B711BC4CEEBF2EE | ++----+--------------------+ +16 rows in set (0.01 sec) +``` + +
    + +Now that the sharded vschema and lookup vindex and its backing table are ready, we can start tablets that will be +used for our new *sharded* `main` keyspace: + +```bash +./202_new_tablets.sh +``` + +
    + +Now we have tablets for our original unsharded `main` keyspace — shard `0` — and one tablet for each of the 4 shards +we'll be using when we reshard the `main` keyspace: + +```bash +$ vtctldclient GetTablets --keyspace=main +zone1-0000000100 main 0 primary localhost:15100 localhost:17100 [] 2023-01-24T04:31:08Z +zone1-0000000200 main -40 primary localhost:15200 localhost:17200 [] 2023-01-24T04:45:38Z +zone1-0000000300 main 40-80 primary localhost:15300 localhost:17300 [] 2023-01-24T04:45:38Z +zone1-0000000400 main 80-c0 primary localhost:15400 localhost:17400 [] 2023-01-24T04:45:38Z +zone1-0000000500 main c0- primary localhost:15500 localhost:17500 [] 2023-01-24T04:45:38Z +``` + +
    + +{{< info >}} +In this example we are deploying 1 tablet per shard and thus disabling the +[semi-sync durability policy](../../configuration-basic/durability_policy/), but in typical production setups each +shard will consist of 3 or more tablets. +{{< /info >}} + +## Perform Resharding + +Now that our new tablets are up, we can go ahead with the resharding: + +```bash +./203_reshard.sh +``` + +
    + +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 +``` + +
    + +This step copies all the data from our source `main/0` shard to our new `main` target shards and sets up +a VReplication workflow to keep the tables on the target in sync with the source. + +You can learn more about what the VReplication [`Reshard` command](../../../reference/vreplication/reshard/) +does and how it works in [the reference page](../../../reference/vreplication/reshard/) and the +[Resharding user-guide](../../configuration-advanced/resharding/). + +We can check the correctness of the copy using the [`VDiff` command](../../../reference/vreplication/vdiff) +and the `.` name we used for `Reshard` command above: + +```bash +$ vtctlclient VDiff -- main.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 +{ + "Workflow": "main2regions", + "Keyspace": "main", + "State": "completed", + "UUID": "044e8da0-9ba4-11ed-8bc7-920702940ee0", + "RowsCompared": 32, + "HasMismatch": false, + "Shards": "-40,40-80,80-c0,c0-", + "StartedAt": "2023-01-24 05:00:26", + "CompletedAt": "2023-01-24 05:00:27" +} +``` + +
    + +We can take a look at the VReplication workflow's progress and status using the +[`Progress` action](../../../reference/vreplication/reshard/#progress): + +```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. +``` + +
    + +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 +complete, we can start cutting-over traffic. This is done via the +[SwitchTraffic](../../../reference/vreplication/reshard/#switchtraffic) actions included in the following scripts: + +```bash +./204_switch_reads.sh +./205_switch_writes.sh +``` + +
    + +Now we can look at how our data is sharded, e.g. by looking at what's stored on the `main/-40` shard: + +```mysql +mysql> show vitess_tablets; ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| Cell | Keyspace | Shard | TabletType | State | Alias | Hostname | PrimaryTermStartTime | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| zone1 | main | -40 | PRIMARY | SERVING | zone1-0000000200 | localhost | 2023-01-24T04:45:38Z | +| zone1 | main | 0 | PRIMARY | SERVING | zone1-0000000100 | localhost | 2023-01-24T04:31:08Z | +| zone1 | main | 40-80 | PRIMARY | SERVING | zone1-0000000300 | localhost | 2023-01-24T04:45:38Z | +| zone1 | main | 80-c0 | PRIMARY | SERVING | zone1-0000000400 | localhost | 2023-01-24T04:45:38Z | +| zone1 | main | c0- | PRIMARY | SERVING | zone1-0000000500 | localhost | 2023-01-24T04:45:38Z | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +5 rows in set (0.00 sec) + +mysql> use main/-40; +Database changed + +mysql> select * from customer; ++----+-----------------+-------------+---------------+ +| id | fullname | nationalid | country | ++----+-----------------+-------------+---------------+ +| 1 | Philip Roth | 123-456-789 | United States | +| 2 | Gary Shteyngart | 234-567-891 | United States | +| 3 | Margaret Atwood | 345-678-912 | Canada | +| 4 | Alice Munro | 456-789-123 | Canada | ++----+-----------------+-------------+---------------+ +4 rows in set (0.01 sec) + +mysql> select id,hex(keyspace_id) from customer_lookup; ++----+--------------------+ +| id | hex(keyspace_id) | ++----+--------------------+ +| 1 | 01166B40B44ABA4BD6 | +| 2 | 0106E7EA22CE92708F | ++----+--------------------+ +2 rows in set (0.00 sec) +``` + +
    + +You can see that only data from US and Canada exists in the `customer` table in this shard. If you look at the +other shards — `40-80`, `80-c0`, and `c0-` — you will see that each shard contains 4 rows in `customer` table. + +The lookup table, however, has a different number of rows per shard. This is because we are using a +[`hash` vindex type](../../../reference/features/vindexes/#predefined-vindexes) to shard the lookup table +which means that it is distributed differently from the `customer` table. We can see an example of this if we +look at the next shard, `40-80`: + +```mysql +mysql> use main/40-80; + +Database changed +mysql> select * from customer; ++----+----------------+-------------+---------+ +| id | fullname | nationalid | country | ++----+----------------+-------------+---------+ +| 5 | Albert Camus | 912-345-678 | France | +| 6 | Colette | 102-345-678 | France | +| 7 | Hermann Hesse | 304-567-891 | Germany | +| 8 | Cornelia Funke | 203-456-789 | Germany | ++----+----------------+-------------+---------+ +4 rows in set (0.00 sec) + +mysql> select id, hex(keyspace_id) from customer_lookup; ++----+--------------------+ +| id | hex(keyspace_id) | ++----+--------------------+ +| 3 | 024EB190C9A2FA169C | +| 5 | 4070BB023C810CA87A | +| 9 | 80692BB9BF752B0F58 | +| 10 | 80594764E1A2B2D98E | +| 13 | C062DCE203C602F358 | +| 15 | C16A8B56ED414942B8 | +| 16 | C15B711BC4CEEBF2EE | ++----+--------------------+ +7 rows in set (0.00 sec) +``` + +## Cleanup + +Now that our resharding work is complete, we can teardown and delete the old `main/0` source shard: + +```bash +./206_down_shard_0.sh +./207_delete_shard_0.sh +``` + +
    + +All we have now is the sharded `main` keyspace and the original unsharded `main` keyspace (shard `0`) no +longer exists: + +```bash +$ vtctldclient GetTablets +zone1-0000000200 main -40 primary localhost:15200 localhost:17200 [] 2023-01-24T04:45:38Z +zone1-0000000300 main 40-80 primary localhost:15300 localhost:17300 [] 2023-01-24T04:45:38Z +zone1-0000000400 main 80-c0 primary localhost:15400 localhost:17400 [] 2023-01-24T04:45:38Z +zone1-0000000500 main c0- primary localhost:15500 localhost:17500 [] 2023-01-24T04:45:38Z +``` + +## Teardown + +Once you are done playing with the example, you can tear the cluster down and remove all of its resources +completely: + +```bash +./301_teardown.sh +``` diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/reparenting.md b/content/en/docs/19.0/user-guides/configuration-advanced/reparenting.md new file mode 100644 index 000000000..499ccea61 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/reparenting.md @@ -0,0 +1,112 @@ +--- +title: Reparenting +weight: 20 +aliases: ['/docs/user-guides/reparenting/'] +--- + +**Reparenting** is the process of changing a shard's primary tablet from one host to another or changing a replica tablet to have a different primary. Reparenting can be initiated manually or it can occur automatically in response to particular database conditions. As examples, you might reparent a shard or tablet during a maintenance exercise or [VTOrc](../../configuration-basic/vtorc) might automatically trigger reparenting when a primary tablet dies. + +This document explains the types of reparenting that Vitess supports: + +* [Active reparenting](../../configuration-advanced/reparenting/#active-reparenting) occurs when Vitess manages the entire reparenting process. +* [External reparenting](../../configuration-advanced/reparenting/#external-reparenting) occurs when another tool handles the reparenting process, and Vitess just updates its topology service, replication graph, and serving graph to accurately reflect primary-replica relationships. + +## MySQL requirements + +### GTIDs + +Vitess requires the use of global transaction identifiers ([GTIDs](https://dev.mysql.com/doc/refman/8.0/en/replication-gtids-concepts.html)) for its operations: + +* During active reparenting, Vitess uses GTIDs to initialize the replication process and then depends on the GTID stream to be correct when reparenting. (During external reparenting, Vitess assumes the external tool manages the replication process.) +* During resharding, Vitess uses GTIDs for [VReplication](../../../reference/vreplication), the process by which source tablet data is transferred to the proper destination tablets. + +### Semisynchronous replication + +Vitess does not depend on [semisynchronous replication](https://dev.mysql.com/doc/refman/8.0/en/replication-semisync.html) but encourages its usage. Larger Vitess deployments typically do implement semisynchronous replication. + +### Active Reparenting + +You can use the following `vtctldclient` commands to perform reparenting operations: + +* `PlannedReparentShard` +* `EmergencyReparentShard` + +Both commands lock the Shard record in the global topology service. The two commands cannot run in parallel, nor can either command run in parallel with the `InitShardPrimary` command. + +Both commands are both dependent on the global topology service being available, and they both insert rows in the topology service's `_vt.reparent_journal` table. As such, you can review your database's reparenting history by inspecting that table. + +### PlannedReparentShard: Planned reparenting + +The `PlannedReparentShard` command reparents a healthy shard to a new primary. It can be used to initialize the shard primary when the shard is brought up. If it is used to change the primary of an already running shard, then both the current and new primary must be up and running. In case the current primary is down, use `EmergencyReparentShard` instead. + +This command performs the following actions when used to change the current primary: + +1. Puts the current primary tablet in read-only mode. +2. Shuts down the current primary's query service, which is the part of the system that handles user SQL queries. At this point, Vitess does not handle any user SQL queries until the new primary is configured and can be used a few seconds later. VTGate can be configured to [buffer](../../../reference/features/vtgate-buffering) these queries for this short duration. +3. Retrieves the current primary's replication position. +4. Instructs the primary-elect tablet to wait for replication data and then begin functioning as the new primary after that data is fully transferred. +5. Ensures replication is functioning properly via the following steps: + - On the primary-elect tablet, insert a row into an internal table and then update the global shard object's PrimaryAlias record. + - In parallel on each replica, including the old primary, set the new primary and wait for the inserted row to replicate to the replica tablet. Replica tablets that had not been replicating before the command was called are left in their current state and do not start replication after the reparenting process. + - Start replication on the old primary tablet so it catches up to the new primary. + +This command performs the following actions when used to initialize the first primary in the shard: +1. Promote the new primary that is specified. +2. Ensures replication is functioning properly via the following steps: + - On the primary-elect tablet, insert a row into an internal table and then update the global shard object's PrimaryAlias record. + - In parallel on each replica, set the new primary and wait for the inserted row to replicate to the replica tablet. + +The new primary (if unspecified) is chosen using the configured [Durability Policy](../../configuration-basic/durability_policy). + +### EmergencyReparentShard: Emergency reparenting + +The `EmergencyReparentShard` command is used to force a reparent to a new primary when the current primary is unavailable. The command assumes that data cannot be retrieved from the current primary because it is dead or not working properly. + +As such, this command does not rely on the current primary at all to replicate data to the new primary. Instead, it makes sure that the primary-elect is the most advanced in replication within all of the available replicas or that the primary-elect has caught up to the most advanced one. In either case, the candidate will only be promoted once it is the most advanced replica. + +**Important**: You can specify which replica you want to be promoted. If not specified, Vitess will choose it for you depending on the durability policies being used. + +This command performs the following actions: + +1. Determines the current replication position on all of the replica tablets and finds the tablet that has the most advanced replication position. +2. Choose a primary-elect tablet based on the durability policy specified, if the user has not specified one using the flags. +3. Wait for the primary-elect to catch up to the most advanced replica, if it isn't already the most advanced. +4. Promotes the primary-elect tablet to be the new primary. In addition to changing its tablet type to primary, the primary-elect performs any other changes that might be required for its new state. +5. Ensures replication is functioning properly via the following steps: + - On the primary-elect tablet, Vitess inserts an entry in a test table and then updates the `PrimaryAlias` record of the global Shard object. + - In parallel on each replica, excluding the old primary, Vitess sets the primary and waits for the test entry to replicate to the replica tablet. Replica tablets that had not been replicating before the command was called are left in their current state and do not start replication after the reparenting process. + +The new primary (if unspecified) is chosen using the configured [Durability Policy](../../configuration-basic/durability_policy). + +### Metrics + +Metrics are available to be seen on the `/debug/vars` page of VTOrc and vtctld for the reparent operations that they execute: + +| Metric | Usage | +|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `planned_reparent_counts` | Number of times Planned Reparent Shard has been run. It is further subdivided by the keyspace, shard and the result of the operation. | +| `emergency_reparent_counts` | Number of times Emergency Reparent Shard has been run. It is further subdivided by the keyspace, shard and the result of the operation. | +| `reparent_shard_operation_timings` | Timings of reparent shard operations indexed by the type of operation. | + +## External Reparenting + +External reparenting occurs when another tool handles the process of changing a shard's primary tablet. After that occurs, the tool needs to call the [`vtctl TabletExternallyReparented`](../../../reference/programs/vtctl/shards/#tabletexternallyreparented) command to ensure that the topology service, replication graph, and serving graph are updated accordingly. + +That command performs the following operations: + +1. Reads the Tablet from the local topology service. +2. Reads the Shard object from the global topology service. +3. If the Tablet type is not already `PRIMARY`, sets the tablet type to `PRIMARY`. +4. The Shard record is updated asynchronously (if needed) with the current primary alias. +5. Any other tablets that still have their tablet type to `PRIMARY` will demote themselves to `REPLICA`. + +The `TabletExternallyReparented` command fails in the following cases: + +* The global topology service is not available for locking and modification. In that case, the operation fails completely. + +Active reparenting might be a dangerous practice in any system that depends on external reparents. You can disable active reparents by starting `vtctld` with the `--disable_active_reparents` flag set to true. (You cannot set the flag after `vtctld` is started.) + +## Fixing Replication + +A tablet can be orphaned after a reparenting if it is unavailable when the reparent operation is running but then recovers later on. Its replication will be automatically fixed by the replication manager or [VTOrc](../../configuration-basic/vtorc). +You can also manually reset the tablet's primary to the current shard primary using the `vtctldclient ReparentTablet` command. You can then restart replication on the tablet if it was stopped by calling the `vtctldclient StartReplication` command. 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 new file mode 100644 index 000000000..e79b15d41 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/resharding.md @@ -0,0 +1,361 @@ +--- +title: Resharding +weight: 15 +aliases: ['/docs/user-guides/resharding/'] +--- + +{{< info >}} +This guide follows on from the Get Started guides. Please make sure that you have +an [Operator](../../../get-started/operator) or [local](../../../get-started/local) installation ready. It also assumes +that the [MoveTables](../../migration/move-tables/) user guide has been followed (which take you through +steps `101`-`205` and more). +{{< /info >}} + +## Preparation + +[Sharding](../../../concepts/shard) enables you to both _initially shard_ or partition your data as well as reshard +your tables — as your data set size grows over time — so that your [keyspace](../../../concepts/keyspace/) is +partitioned across several underlying [tablets](../../../concepts/tablet). A sharded keyspace has some additional +restrictions on both [query syntax](../../../reference/compatibility/mysql-compatibility) and features such as +`auto_increment`, so it is helpful to plan out a reshard operation diligently. However, you can always +_reshard again_ later if your sharding scheme turns out to be suboptimal. + +Using our example `commerce` and `customer` keyspaces, lets work through the two most common issues. + +### Sequences + +The first issue to address is the fact that customer and corder have auto-increment columns. This scheme does not work +well in a sharded setup. Instead, Vitess provides an equivalent feature called [sequences](../../../reference/features/vitess-sequences/). + +The sequence table is an unsharded single row table that Vitess can use to generate monotonically increasing IDs. +The syntax to generate IDs is: `select next value from customer_seq` or `select next N values from customer_seq`. +The `vttablet` that exposes this table is capable of serving a very large number of such IDs because values are +reserved in chunks, then cached and served from memory. The chunk/cache size is configurable via the [`cache` +value](../../../reference/features/vitess-sequences/#initializing-a-sequence). + +The VSchema allows you to associate the column of a table with the sequence table. Once this is done, an `INSERT` +on that table transparently fetches an ID from the sequence table, fills in the value in the new row, and then +routes the row to the appropriate shard. This makes the construct backward compatible to how [MySQL's +`auto_increment`](https://dev.mysql.com/doc/refman/en/example-auto-increment.html) works. + +Since sequences table must be unsharded, they will be stored in the unsharded `commerce` keyspace. Here is the +schema used: + +```sql +CREATE TABLE customer_seq (id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +INSERT INTO customer_seq (id, next_id, cache) VALUES (0, 1000, 100); +CREATE TABLE order_seq (id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +INSERT INTO order_seq (id, next_id, cache) VALUES (0, 1000, 100); +``` + +
    + +Note the `vitess_sequence` comment in the create table statement. VTTablet will use this metadata to treat this +table as a sequence. About the values we specified above: + +* `id` is always 0 +* `next_id` is set to `1000`: the value should be comfortably greater than the max `auto_increment` used so far. +* `cache` specifies the number of values to reserve and cache before the primary `vttablet` for the `commerce` +keyspace updates `next_id` to reserve and cache the next chunk of IDs. + +Larger cache values perform better but can exhaust the available values more quickly since e.g. during reparent +operations the new PRIMARY `vttablet` will start off at the `next_id` value and any unused values from the +previously reserved chunk are lost. + +The [VTGate servers](../../../concepts/vtgate/) also need to know about the sequence tables. This is done by +updating the [VSchema](../../../concepts/vschema/) for the `commerce` keyspace as follows: + +```json +{ + "tables": { + "customer_seq": { + "type": "sequence" + }, + "order_seq": { + "type": "sequence" + }, + "product": {} + } +} +``` + +### Vindexes + +The next decision is about the sharding keys or +[Primary Vindexes](../../../reference/features/vindexes/#the-primary-vindex). This is a complex decision +that involves the following considerations: + +* What are the highest QPS queries, and what are the `WHERE` clauses for them? +* Cardinality of the column — it must be high. +* Do we want some rows to live together to support in-shard joins (data locality)? +* Do we want certain rows that will be in the same transaction to live together (data locality)? + +Using the above considerations, in our use case, we can determine the following: + +* For the customer table, the most common `WHERE` clause uses `customer_id`. So `customer_id` is declared as the + [Primary Vindex](../../../reference/features/vindexes/#the-primary-vindex) for that table. +* Given that the customer table has a lot of rows, its cardinality is also high. +* For the corder table, we have a choice between `customer_id` and `order_id`. Given that our app joins `customer` + with `corder` quite often on the `customer_id` column, it will be beneficial to choose `customer_id` as the Primary + Vindex for the `corder` table as well so that we have data locality for those joins and can avoid costly cross-shard operations. +* Coincidentally, transactions also update `corder` tables with their corresponding `customer` rows. This further + reinforces the decision to use `customer_id` as Primary Vindex. + +There are a couple of other considerations which are out of scope for now, but worth mentioning: + +* It may also be worth creating a [secondary lookup Vindex](../../../reference/features/vindexes/#secondary-vindexes) +on `corder.order_id`. +* Sometimes the `customer_id` is really a `tenant_id`. For example, if your application is a SaaS, which serves tenants +that themselves have customers. One key consideration here is that the sharding by the `tenant_id` can lead to +unbalanced shards. You may also need to consider sharding by the tenant's `customer_id`. + +Putting it all together, we have a VSchema similar to the following for the `customer` keyspace: + +```json +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "customer": { + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "customer_id", + "sequence": "customer_seq" + } + }, + "corder": { + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "order_id", + "sequence": "order_seq" + } + } + } +} +``` + +
    + +Since the primary vindex columns here use the +[`BIGINT` MySQL integer type](https://dev.mysql.com/doc/refman/en/integer-types.html), we choose `hash` as +the primary [vindex type](../../../reference/features/vindexes/#predefined-vindexes), which is a pseudo-random +way of distributing rows into various shards. For other data types we would typically use a different vindex +type: + +* For `VARCHAR` columns, use `unicode_loose_md5` or `unicode_loose_xxhash`. +* For `VARBINARY`, use `binary_md5` or `xxhash`. +* Vitess uses a plugin system to define vindexes. If none of the +[predefined vindexes](../../../reference/features/vindexes/#predefined-vindexes) suit your needs, you can +develop your own custom vindex. + +## Apply VSchema + +Applying the new VSchema instructs Vitess that the keyspace is sharded, which may prevent some complex queries. It is a +good idea to [validate this](../../sql/vtexplain) before proceeding with this step. If you do notice that certain +queries start failing, you can always revert temporarily by restoring the old VSchema. Make sure you fix all of the +queries before proceeding to the [Reshard](../../../reference/vreplication/reshard/) process. + +### Using Operator + +```bash +vtctldclient ApplySchema --sql="$(cat create_commerce_seq.sql)" commerce +vtctldclient ApplyVSchema --vschema="$(cat vschema_commerce_seq.json)" commerce +vtctldclient ApplyVSchema --vschema="$(cat vschema_customer_sharded.json)" customer +vtctldclient ApplySchema --sql="$(cat create_customer_sharded.sql)" customer +``` + +### Using a Local Deployment + +```bash +vtctldclient ApplySchema --sql-file create_commerce_seq.sql commerce +vtctldclient ApplyVSchema --vschema-file vschema_commerce_seq.json commerce +vtctldclient ApplyVSchema --vschema-file vschema_customer_sharded.json customer +vtctldclient ApplySchema --sql-file create_customer_sharded.sql customer +``` + +## Create New Shards + +At this point, you have finalized your sharded VSchema and vetted all the queries to make sure they still work. Now, +it’s time to reshard. + +The resharding process works by splitting existing shards into smaller shards. This type of resharding is the most +appropriate for Vitess. There are some use cases where you may want to bring up a new shard and add new rows in the +most recently created shard. This can be achieved in Vitess by splitting a shard in such a way that no existing rows +end up in the new shard. However, it's not natural for Vitess. We now have to create the new target shards: + +### Using Operator + +```bash +kubectl apply -f 302_new_shards.yaml +``` + +
    + +Make sure that you restart the port-forward after you have verified with `kubectl get pods` that this operation has +completed: + +```bash +killall kubectl +./pf.sh & +``` + +### Using a Local Deployment + +```bash +./302_new_shards.sh +``` + +## Start the Reshard + +Now we can start the [Reshard](../../../reference/vreplication/reshard/) operation. It occurs online, and +will not block any read or write operations to your database: + +```bash +vtctlclient Reshard -- --source_shards '0' --target_shards '-80,80-' Create customer.cust2cust +``` + +
    + +All of the command options and parameters for `Reshard` are listed in +our [reference page for Reshard](../../../reference/vreplication/reshard). + +## Validate Correctness + +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 +VDiff 60fa5738-9bad-11ed-b6de-920702940ee0 scheduled on target shards, use show to view progress + +$ vtctlclient VDiff -- --format=json customer.cust2cust show last +{ + "Workflow": "cust2cust", + "Keyspace": "customer", + "State": "completed", + "UUID": "60fa5738-9bad-11ed-b6de-920702940ee0", + "RowsCompared": 10, + "HasMismatch": false, + "Shards": "-80,80-", + "StartedAt": "2023-01-24 06:07:27", + "CompletedAt": "2023-01-24 06:07:28" +} +``` + +## Switch Non-Primary Reads + +After validating for correctness, the next step is to switch +[`REPLICA` and `RDONLY` targeted read operations](../../../reference/features/vschema/#tablet-types) to occur +at the new location. By switching targeted read operations first, we are able to verify that the new shard's +tablets are healthy and able to respond to requests: + +```bash +vtctlclient Reshard -- --tablet_types=rdonly,replica SwitchTraffic customer.cust2cust +``` + +## Switch Writes and Primary Reads + +After the [`REPLICA` and `RDONLY` targeted reads](../../../reference/features/vschema/#tablet-types) have been +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 +``` + +## Note + +While we have switched tablet type targeted reads and writes separately in this example, you can also switch +all traffic at the same time. This is done by default as if you don't specify the `--tablet_types` parameter +then `SwitchTraffic` will start serving all traffic from the target for all tablet types. + +You should now be able to see the data that has been copied over to the new shards (assuming you +previously loaded this data in the [`MoveTable` user-guide](../../migration/move-tables/)): + +```bash +$ mysql --table < ../common/select_customer-80_data.sql +Using customer/-80 +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ + +$ mysql --table < ../common/select_customer80-_data.sql +Using customer/80- +Customer ++-------------+----------------+ +| customer_id | email | ++-------------+----------------+ +| 4 | dan@domain.com | ++-------------+----------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 4 | 4 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ +``` + +## Finalize and Cleanup + +After celebrating your second successful resharding, you are now ready to clean up the leftover artifacts: + +### Using Operator + +```bash +vtctlclient Reshard -- Complete customer.cust2cust +``` +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 +``` + +### Using a Local Deployment + +```bash +vtctlclient Reshard -- Complete customer.cust2cust + +for i in 200 201 202; do + CELL=zone1 TABLET_UID=$i ./scripts/vttablet-down.sh + CELL=zone1 TABLET_UID=$i ./scripts/mysqlctl-down.sh +done + +vtctldclient DeleteShards --recursive customer/0 +``` + +
    + +These are the steps taken in the `306_down_shard_0.sh` and `307_delete_shard_0.sh` scripts. In the first script (`306`) +we stop all tablet instances for shard 0. This will cause all those `vttablet` and `mysqld` processes to be stopped. +In the second script (`307`) we delete the shard records from our Vitess cluster topology. +Beyond this, you will also want to manually delete the on-disk directories associated with this shard. With the local examples that would be: + +```bash +rm -rf ${VTDATAROOT}/vt_000000020{0,1,2}/ +``` diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/shard-isolation-atomicity.md b/content/en/docs/19.0/user-guides/configuration-advanced/shard-isolation-atomicity.md new file mode 100644 index 000000000..e7bd91acd --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/shard-isolation-atomicity.md @@ -0,0 +1,187 @@ +--- +title: Shard Isolation and Atomicity Model +weight: 55 +aliases: ['/docs/user-guides/shard-isolation-atomicity/'] +--- + +This is meant to explain some of the practical effects of the Vitess multi-shard isolation and atomicity model touched on in [Vitess' scalability philosophy](../../../overview/scalability-philosophy/#consistency-model). + +{{< info >}} +A note about naming: When talking about multi-shard atomicity and isolation informally, we may talk about it as "consistency", but in the context of **ACID** (atomicity, consistency, isolation, durability) as it is applied in a database context, this is incorrect. For this document, we will attempt to use the more precise terms. +{{< /info >}} + +## Introduction + +For a sharded database (keyspace) Vitess maintains multiple, independent MySQL instances. Each of these instances is a member of a single **shard**, and contains a subset of the rows for one or more tables in the keyspace, dependent on the sharding strategy selected for that table according to the **vschema** for that keyspace. + +When it comes to dealing with **isolation** and **atomicity** in the database sense (i.e. the `I` and `A` in `ACID`), there are two main issues in a sharded environment like Vitess: + + * Cross-shard isolation + * Cross-shard atomicity + +Before we dive in, let us state that in the simple case, where a read (`SELECT`) or write (`INSERT`, `UPDATE`, `DELETE`) only addresses data in a single shard, there are no cross-shard concerns, and in general, both the isolation and atomicity guarantees are similar (or the same) to that of MySQL. + +## Cross-shard isolation + +Because cross-shard writes might not be [completely atomic](../shard-isolation-atomicity/#cross-shard-atomicity), cross-shard primary reads (even if they all go to the primary) might not display **isolation**, i.e. they may show partial results for in-flight cross-shard write operations. A simple example may be that the all the rows for a multi-valued insert might not become visible across all shards at the same time. + +This is typically not a big issue for most applications, since so-called read-after-write consistency is retained, e.g.: + + * if you performed a multi-value insert across multiple shards, + * **and** it completed successfully + * **then** if you issue a multi-shard (primary) read after this, you should see the results of what you wrote across all shards (assuming nothing else deleted/updated those rows in the meanwhile) + +### Note + +If you perform replica or rdonly reads instead of primary reads (using the `@replica` or `@rdonly` Vitess dbname syntax extension), you will face the same issues you would if you read from a single MySQL replica instance. Accordingly, writes might not become visible for an extended period of time, depending on **replica lag**. That being said, since Vitess helps you to keep your individual primary instances smaller, replica lag should be less of an issue than it would be with an unsharded large MySQL setup. + +## Cross-shard atomicity + +When performing a write (`INSERT`, `UPDATE`, `DELETE`) across multiple shards, Vitess attempts to optimize performance, while also trying to ensure as much **atomicity** as possible. That is, Vitess will attempt to ensure that the whole write operation succeeds across all shards, or is rolled back. However, if you think about what actually needs to happen across the multiple shards, achieving full atomicity across a (potentially large) number of shards can be very expensive. As a result, Vitess does not even try to guarantee cross-shard **isolation**, but rather focuses on trying to optimize cross-shard **atomicity**. The difference here is that while the results of a single transaction might not become visible across all shards in the same instant, Vitess does try to ensure that write failures on a subset of the shards are: + + * rolled back + * or if they cannot be rolled back, the application receives a reasonable error to that effect. + +As an example, imagine an insert of 20 rows into a sharded table with 4 shards. There are many ways for Vitess to take an insert like this and perform the inserts to the backend shards: + +### Method 1: The naive way + +The first method would be to launch an autocommit insert of the subset of rows for each shard to the 4 shards. This would insert concurrently across the 4 shards, so would be great for performance. However, there are significant drawbacks: + + * What do we do if any of them fail? + * What do we do if any/all of them time out? + +As a result we might not even be able to tell the application with some certainty what happened. However, for some use-cases the performance of this option might be desirable. It is possible to select this behavior for individual DML statements in Vitess by using the special Vitess comment: + +```sh +/*vt+ MULTI_SHARD_AUTOCOMMIT=1 */ +``` + +It is not possible to make this the default behavior in Vitess; i.e. you will have to change your application code to take advantage of this option. + +In the [examples](https://github.com/vitessio/vitess/tree/main/examples/vtexplain), we have a script, [`atomicity_method1.sh`](https://github.com/vitessio/vitess/tree/main/examples/vtexplain/atomicity_method1.sh); which tries to use a sample vschema from `atomicity_vschema.json` and SQL schema in `atomicity_schema.sql` to illustrate this method. Let's run this and inspect the output: + +```sh +$ ./method1.sh ++ vtexplain --vschema-file atomicity_vschema.json --schema-file atomicity_schema.sql --shards 4 --sql 'INSERT /*vt+ MULTI_SHARD_AUTOCOMMIT=1 */ INTO t1 (c1) values (1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12),(13),(14),(15),(16),(17),(18),(19),(20);' +---------------------------------------------------------------------- +INSERT /*vt+ MULTI_SHARD_AUTOCOMMIT=1 */ INTO t1 (c1) values (1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12),(13),(14),(15),(16),(17),(18),(19),(20) + +1 ks1/-40: insert /*vt+ MULTI_SHARD_AUTOCOMMIT=1 */ into t1(c1) values (10), (14), (15), (16) +1 ks1/40-80: insert /*vt+ MULTI_SHARD_AUTOCOMMIT=1 */ into t1(c1) values (8), (17), (18) +1 ks1/80-c0: insert /*vt+ MULTI_SHARD_AUTOCOMMIT=1 */ into t1(c1) values (2), (3), (4), (7), (9), (12), (13), (19), (20) +1 ks1/c0-: insert /*vt+ MULTI_SHARD_AUTOCOMMIT=1 */ into t1(c1) values (1), (5), (6), (11) + +---------------------------------------------------------------------- +``` + +As can be seen from this output, we just issue all the inserts with the subset of values destined for each shard without any transactions. + +### Method 2: The I-don't-want-this way (a.k.a. SINGLE) + +In certain situations, a schema may be constructed in a fashion where cross-shard writes are very rare (or should not happen). In a situation like this Vitess provides for a transaction mode (set via the MySQL set statement `set transaction_mode = 'single'`) called **SINGLE**. In this transaction mode, any write that needs to span multiple shards will fail with an error. Similarly, any **transactional read** (i.e. using `BEGIN` & `COMMIT`) that spans multiple shards will also get an error. + +Here is our example for this case using `vtexplain` and [`atomicity_method2.sh`](https://github.com/vitessio/vitess/tree/main/examples/vtexplain/atomicity_method2.sh): + +```sh +$ ./method2.sh ++ vtexplain --vschema-file atomicity_vschema.json --schema-file atomicity_schema.sql --shards 4 --sql 'SET transaction_mode="single"; INSERT INTO t1 (c1) values (1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12),(13),(14),(15),(16),(17),(18),(19),(20);' +E0803 16:54:09.738322 89168 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +E0803 16:54:09.738352 89168 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +E0803 16:54:09.738431 89168 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +E0803 16:54:09.739161 89168 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +ERROR: vtexplain execute error in 'INSERT INTO t1 (c1) values (1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12),(13),(14),(15),(16),(17),(18),(19),(20)': multi-db transaction attempted: [target:{keyspace:"ks1" shard:"40-80" tablet_type:PRIMARY} transaction_id:1628034849705415307 tablet_alias:{cell:"explainCell" uid:2} target:{keyspace:"ks1" shard:"80-c0" tablet_type:PRIMARY} transaction_id:1628034849709028116 tablet_alias:{cell:"explainCell" uid:3} target:{keyspace:"ks1" shard:"-40" tablet_type:PRIMARY} transaction_id:1628034849700176113 tablet_alias:{cell:"explainCell" uid:1} target:{keyspace:"ks1" shard:"c0-" tablet_type:PRIMARY} transaction_id:1628034849710978055 tablet_alias:{cell:"explainCell" uid:4}] +multi-db transaction attempted: [target:{keyspace:"ks1" shard:"40-80" tablet_type:PRIMARY} transaction_id:1628034849705415307 tablet_alias:{cell:"explainCell" uid:2} target:{keyspace:"ks1" shard:"80-c0" tablet_type:PRIMARY} transaction_id:1628034849709028116 tablet_alias:{cell:"explainCell" uid:3} target:{keyspace:"ks1" shard:"-40" tablet_type:PRIMARY} transaction_id:1628034849700176113 tablet_alias:{cell:"explainCell" uid:1}] +multi-db transaction attempted: [target:{keyspace:"ks1" shard:"40-80" tablet_type:PRIMARY} transaction_id:1628034849705415307 tablet_alias:{cell:"explainCell" uid:2} target:{keyspace:"ks1" shard:"80-c0" tablet_type:PRIMARY} transaction_id:1628034849709028116 tablet_alias:{cell:"explainCell" uid:3}] +``` + +As expected, we start getting errors since we are attempting a Vitess "transaction" across multiple shards. + +If we limited ourselves to writes that only target a single one of the multiple shards, this would work fine, e.g.: + +```sh +$ ./method2_working.sh ++ vtexplain --vschema-file atomicity_vschema.json --schema-file atomicity_schema.sql --shards 4 --sql 'SET transaction_mode="single"; INSERT INTO t1 (c1) values (10),(14),(15),(16);' +---------------------------------------------------------------------- +SET transaction_mode="single" + + +---------------------------------------------------------------------- +INSERT INTO t1 (c1) values (10),(14),(15),(16) + +1 ks1/-40: insert into t1(c1) values (10), (14), (15), (16) + +---------------------------------------------------------------------- +``` + +Here is the result if we attempted a transactional read across shards while in `transaction_mode` of `single` (note the `BEGIN` and `COMMIT` in the query): + +```sh +$ ./method2_reads.sh ++ vtexplain --vschema-file atomicity_vschema.json --schema-file atomicity_schema.sql --shards 4 --sql 'SET transaction_mode="single"; BEGIN; SELECT * from t1; COMMIT;' +E0803 17:00:49.524545 89777 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +E0803 17:00:49.524549 89777 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +E0803 17:00:49.524581 89777 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +E0803 17:00:49.524661 89777 tabletserver.go:1368] unknown error: unsupported query rollback (errno 1105) (sqlstate HY000): Sql: "rollback", BindVars: {} +ERROR: vtexplain execute error in 'SELECT * from t1': multi-db transaction attempted: [target:{keyspace:"ks1" shard:"c0-" tablet_type:PRIMARY} transaction_id:1628035249495856333 tablet_alias:{cell:"explainCell" uid:4} target:{keyspace:"ks1" shard:"80-c0" tablet_type:PRIMARY} transaction_id:1628035249493377809 tablet_alias:{cell:"explainCell" uid:3} target:{keyspace:"ks1" shard:"-40" tablet_type:PRIMARY} transaction_id:1628035249485888657 tablet_alias:{cell:"explainCell" uid:1} target:{keyspace:"ks1" shard:"40-80" tablet_type:PRIMARY} transaction_id:1628035249490426670 tablet_alias:{cell:"explainCell" uid:2}] +multi-db transaction attempted: [target:{keyspace:"ks1" shard:"c0-" tablet_type:PRIMARY} transaction_id:1628035249495856333 tablet_alias:{cell:"explainCell" uid:4} target:{keyspace:"ks1" shard:"80-c0" tablet_type:PRIMARY} transaction_id:1628035249493377809 tablet_alias:{cell:"explainCell" uid:3} target:{keyspace:"ks1" shard:"-40" tablet_type:PRIMARY} transaction_id:1628035249485888657 tablet_alias:{cell:"explainCell" uid:1}] +multi-db transaction attempted: [target:{keyspace:"ks1" shard:"c0-" tablet_type:PRIMARY} transaction_id:1628035249495856333 tablet_alias:{cell:"explainCell" uid:4} target:{keyspace:"ks1" shard:"80-c0" tablet_type:PRIMARY} transaction_id:1628035249493377809 tablet_alias:{cell:"explainCell" uid:3}] +``` + + +### Method 3: The default way + +By default, Vitess employs a default setting for `transaction_mode` of **MULTI** (`set transaction_mode = 'multi'`). This mode is a tradeoff between atomicity, isolation and performance, where Vitess will attempt to minimize (but not guarantee) the chances of a partial cross-shard update. What Vitess does in a case like this is: + + * Phase 1: Open transactions to each of the shards. If anything fails during this phase, nothing has been written, the application sees an error, and can cleanly retry. These transactions are opened in parallel for best performance. + * Phase 2: Issue the subset of inserts for each shard. This is also done in parallel. An error at this point will allow us to rollback the transactions on the shards. Again, no data has been affected, and the application can retry. + * Phase 3: Issue commits against each shard involved in the insert. This is done serially. This allows the operation to halt if there is an error on one of the shards. At this point an error would be returned to the application, **but the inserts on shards committed before the failing shard cannot be rolled back**. As a result the atomicity of the insert is broken, and now clients will see (possibly permanently) inconsistent results. It is left up to the client to repair the possible inconsistency, potentially with a retry, or some more elaborate mechanism. + +#### Notes: + +* As an optimization Phase 1+2 are performed at the same time, see below. +* Because parts of this proceeds serially, the latency of the overall insert is typically proportional to the number of shards that the insert is scattered across. + +Let's run our example for this case [`atomicity_method3.sh`](https://github.com/vitessio/vitess/tree/main/examples/vtexplain/atomicity_method3.sh) and inspect the output: + +```sh +$ ./method3.sh ++ vtexplain --vschema-file atomicity_vschema.json --schema-file atomicity_schema.sql --shards 4 --sql 'INSERT INTO t1 (c1) values (1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12),(13),(14),(15),(16),(17),(18),(19),(20);' +---------------------------------------------------------------------- +INSERT INTO t1 (c1) values (1),(2),(3),(4),(5),(6),(7),(8),(9),(10),(11),(12),(13),(14),(15),(16),(17),(18),(19),(20) + +1 ks1/-40: begin +1 ks1/-40: insert into t1(c1) values (10), (14), (15), (16) +1 ks1/40-80: begin +1 ks1/40-80: insert into t1(c1) values (8), (17), (18) +1 ks1/80-c0: begin +1 ks1/80-c0: insert into t1(c1) values (2), (3), (4), (7), (9), (12), (13), (19), (20) +1 ks1/c0-: begin +1 ks1/c0-: insert into t1(c1) values (1), (5), (6), (11) +2 ks1/40-80: commit +3 ks1/80-c0: commit +4 ks1/c0-: commit +5 ks1/-40: commit + +---------------------------------------------------------------------- +``` + +The numbers on the left of the output indicate the ordering of operations, i.e. everything with the number `1` are performed concurrently. Here we can see that Phase 1 and 2 are initiated across all the shards for the multi-sharded insert concurrently. It is only in Phase 3 when we start doing the commits to each of the shards in serial, which allows us to abandon or roll back changes to at least a subset of the shards if something goes wrong between the `2 ks1/40-80: commit` and the `5 ks1/-40: commit`. + + +### Method 4: The TWOPC way + +Vitess also supports (assuming the vtgate and vttablets have been configured appropriately) a two-phase commit option for multi-shard writes. This is enabled by using the non-default setting for `transaction_mode` of **TWOPC**. In this mode, Vitess can guarantee atomicity for cross-shard writes; but still does not guarantee isolation; i.e. other clients can still see partial commits across shards. + +It should be emphasized that if you need to use **TWOPC** extensively in your application, you may be using Vitess incorrectly; the vast majority of Vitess users do not use it at all. + +See our [TWOPC page](../../../reference/features/two-phase-commit/) for more details on how to configure **TWOPC**. + +In TWOPC mode, Vitess uses the `_vt` sidecar database to record metadata related to each transactions across multiple tables. As a result, any multi-shard write in **TWOPC** mode is likely to be an order of a magnitude slower than in **MULTI** mode. + +Unfortunately, we cannot use `vtexplain` to illustrate the working of TWOPC mode. + + +## In closing + +From the above examples, it should be clear that as the number of shards increase, large write operations that span multiple shards become more problematic from a performance point of view. It is therefore important for Vitess keyspaces (databases) that will span a large number of shards to be designed in a way that individual writes will affect a minimum of shards. diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/static-auth.md b/content/en/docs/19.0/user-guides/configuration-advanced/static-auth.md new file mode 100644 index 000000000..42e3c0921 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/static-auth.md @@ -0,0 +1,154 @@ +--- +title: File based authentication +weight: 2 +--- + +The simplest way to configure users is using a `static` auth method, and we +can define the users in a JSON formatted file or string. + +```sh +$ cat > users.json << EOF +{ + "vitess": [ + { + "UserData": "vitess", + "Password": "supersecretpassword" + } + ], + "myuser1": [ + { + "UserData": "myuser1", + "Password": "password1" + } + ], + "myuser2": [ + { + "UserData": "myuser2", + "Password": "password2" + } + ] +} +EOF +``` + +Then we can load this into VTGate with the additional commandline parameters: +```sh +vtgate $(cat < SELECT UPPER(SHA1(UNHEX(SHA1("password")))) as hash; ++------------------------------------------+ +| hash | ++------------------------------------------+ +| 2470C0C06DEE42FD1618BB99005ADCA2EC9D1E19 | ++------------------------------------------+ +1 row in set (0.01 sec) +``` + +So, you would use `*2470C0C06DEE42FD1618BB99005ADCA2EC9D1E19` as the +`MysqlNativePassword` hash value for the cleartext password `password`. + + +## UserData + +In the static authentication JSON file, the `UserData` string is **not** +the username; the username is the string key for the list. The `UserData` +string does **not** need to correspond to the username, and is used by the +[authorization mechanism](../authorization) when referring to a user. It is +usually however simpler if you make the `UserData` string and the username +the same. + +The `UserData` feature can be leveraged to create multiple users that are +equivalent to the authorization layer (i.e. multiple users having the same +`UserData` strings), but are different in the authentication layer (i.e. +have different usernames and passwords). + +## Multiple passwords + +A very convenient feature of the VTGate authorization is that, as can be +seen in the example JSON authentication files, you have a **list** of +`UserData` and `Password`/`MysqlNativePassword` pairs associated with +a user. You can optionally leverage this to assign multiple different +passwords to a single user, and VTGate will allow a user to authenticate +with any of the defined passwords. This makes password rotation +much easier; and less likely to require or cause downtime. + +An example could be: +```json +{ + "vitess": [ + { + "UserData": "vitess_old", + "MysqlNativePassword": "*9E128DA0C64A6FCCCDCFBDD0FC0A2C967C6DB36F" + }, + { + "UserData": "vitess_new", + "MysqlNativePassword": "*B3AD996B12F211BEA47A7C666CC136FB26DC96AF" + } + ] +} +``` + +This feature also allows different `UserData` strings +to be associated with a user depending on the password used. This can +be used in concert with the [authorization mechanism](../authorization) to +migrate an application gracefully from one set of ACLs (or no ACLs) +to another set of ACLs, by just changing the password used by the +application. + +In the example above, the username `vitess` has **two different** passwords +that would be allowed, each resulting in different `UserData` strings +(`vitess_old` or `vitess_new`) being passed to the VTTablet layer that can +be used for authorization/ACL enforcement. diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/trace1.png b/content/en/docs/19.0/user-guides/configuration-advanced/trace1.png new file mode 100644 index 000000000..93486434c Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-advanced/trace1.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/tracing.md b/content/en/docs/19.0/user-guides/configuration-advanced/tracing.md new file mode 100644 index 000000000..465726d4a --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/tracing.md @@ -0,0 +1,80 @@ +--- +title: Tracing +weight: 40 +aliases: ['/docs/user-guides/tracing/'] +--- + +# Vitess tracing + +Vitess allows you to generate Jaeger / OpenTracing compatible trace events from the Vitess major server components: `vtgate`, `vttablet`, and `vtctld`. To sync these trace events you need an OpenTracing compatible server (e.g. Jaeger). Vitess can send tracing events to this server in the Jaeger compact Thrift protocol wire format which is usually UDP on port 6381. + +## Configuring tracing + +The first step of configuring tracing is to make sure you have tracing collectors properly setup. The tracing collectors must be located where they can be reached from the various Vitess components on which you want to configure tracing. We will not cover the entire setup process in this guide. The guide will cover the minimal config for testing/running locally, using the Jaeger docker container running on `localhost`. You can read more about Jaeger [here](https://www.jaegertracing.io/docs/1.20/features/). + +### Running Jaeger in docker + +You can follow the Jaeger getting started documentation [here](https://www.jaegertracing.io/docs/1.20/getting-started/). In essence you need to run the Jaeger docker container: + +``` shell +$ docker run -d --name jaeger \ + -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \ + -p 5775:5775/udp \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 5778:5778 \ + -p 16686:16686 \ + -p 14268:14268 \ + -p 14250:14250 \ + -p 9411:9411 \ + jaegertracing/all-in-one:1.20 +``` + +Note that you don't need to expose all these ports, Vitess only cares about port 6831 (the UDP compact Thrift Jaeger protocol listener). You will also need port 16686 for the Jaeger web UI to browse the spans reported. + +### Configuring tracing for vtgate, vttablet and vtctld + +Now that you have the Jaeger server running, you can add the necessary startup options to `vtgate`, `vttablet` and `vtctld`. This will enable you to send trace spans to the server. The command line options for doing this are the same across `vtgate`, `vttablet` and `vtctld`. Add the following options for a tracing agent running on the `localhost`: + +``` shell +--tracer opentracing-jaeger --jaeger-agent-host 127.0.0.1:6831 --tracing-sampling-rate 0.0 +``` + +There are a few things to note: + + * There are other tracing plugins and the `-tracer` option allows you to select them. Currently we have `opentracing-jaeger` and `opentracing-datadog`. Only `opentracing-jaeger` is covered in this document. + * `--jaeger-agent-host` should point to the `hostname:port` or `ip:port` of the tracing collector running the Jaeger compact Thrift protocol. + * The tracing sample rate (`--tracing-sampling-rate`) is expressed as a fraction from 0.0 (no sampling) to 1.0 (100% of all events are sent to the server). In the example, this option is set to zero, because we will be passing custom span contexts to the queries we want to trace. In this way, we only instrument the queries we want. This is recommended for large installations because it is typically very hard to organize and consume the volume of tracing events generated by even a small fraction of events from a non-trivial production Vitess system. However, if you just want events to flow automatically without you having to instrument queries, you can set this to a value other than `0.0` and skip the following section on instrumenting queries. + +After adding these options, you must restart the Vitess components in question. + +### Instrumenting queries + +Now that you have the Vitess components setup, you can start instrumenting your queries to choose which queries (or application actions) for which you want to generate trace events. This is obviously an application-specific process, but there are a few things to note: + + * The `SpanContext` id you have to instrument your Vitess queries with, in order for them to generate trace events, has a very specific format. It is recommended to use one of the Jaeger / OpenTracing client libraries to generate these for you. They take the format of a base64 string of a JSON object that, at it simplest, looks something like [this](https://www.jaegertracing.io/docs/1.19/client-libraries/#tracespan-identity): + + ``` shell + {"uber-trace-id":"{trace-id}:{span-id}:{parent-span-id}:{flags}"} + ``` + Note the very specific format requirements in the documentation. Because of these requirements, it can be tiresome to generate them yourself, and it is more convenient to use the client libraries instead. + + * Once you have the `SpanContext` string in its encoded base64 format, you can then generate your SQL query/queries related to this span to send them to Vitess. To inform Vitess of the `SpanContext`, you need to use a special SQL comment style, e.g.: + + ``` shell + /*VT_SPAN_CONTEXT=*/ SELECT * from product; + ``` + There are additional notes here: + + * The underlying tracing libraries are very particular about the base64 value, so if you have any formatting problems (including trailing spaces between the base64 value and the closing of the comment); you will get many warnings in your `vtgate` logs. + * When testing with, for example, the `mysql` CLI tool, make sure you are using the `-c` (or `--comments` flag), since the default is `--skip-comments`, which will never send your comments to the server (`vtgate`). + +### Inspecting trace spans in the Jaeger web UI + +This is beyond the scope of this guide. However, in general, if you have set everything above up correctly and you have instrumented and executed some queries appropriately, you can now access the Jager web UI to look at the spans recorded. If you are using the local docker container version of Jaeger, you can access the web UI in your browser at http://localhost:16686/. + +You should be able to search for and find spans based on the `trace-id` or `span-id` with which your query/queries were instrumented. Once you find a query, you will be able to see the trace events emitted by different +parts of the code as the query moves through `vtgate` and the `vttablet(s)` involved in the query. An example would look something like this: + +![](../trace1.png) + diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/transport-security-model.md b/content/en/docs/19.0/user-guides/configuration-advanced/transport-security-model.md new file mode 100644 index 000000000..ff48dd73d --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/transport-security-model.md @@ -0,0 +1,761 @@ +--- +title: Securing Vitess Using TLS +weight: 60 +--- + +## Introduction + +Vitess has a number of different components that, in most real-world configurations, connect to each other over the network. Many organizations require, for compliance or practical reasons, that these communications +be encrypted and/or authenticated. This guide will provide an overview of these client/server combinations between components, what the encryption and authentication options are, and a walkthrough on how to configure Vitess to use them. You can read more about our [transport security model](../../../reference/features/transport-security-model/) in our references. + +There are two paths a data path and a control path that could be secured. The focus in the guide will be to secure the data path. You can read more about the two paths [here](../../configuration-basic/ports/). + +Note that the sensitive information mainly flows over the data path, and depending on your deployment model, you may not have to encrypt all of the the control or meta-data path. We recommend that you evaluate your needs in the context of your compliance directives, threat model and risk management framework. + +It should also be noted that while Vitess provides the mechanism for securing these communication channels, it does **not** manage the certificate management tasks like: + + * Securely generating private keys + * Issuing server certificates + * Issuing, if necessary, client certificates + * Certificate rotation + * Certificate audit + +Indeed, the hardest part of deploying TLS with Vitess in a large organization may be to integrate with whatever certificate policies and procedures the organization mandates. It should be noted that the manual issuing and rotation of certificates in a Vitess environment of a non-trivial size is impractical, and some provisioning and configuration management automation will need to be built. + +## Protocols involved + +Of all the data, meta-data and control paths enumerated above, they use one of three protocols: + + * MySQL binary protocol + * gRPC (using HTTP/2 as transport) + * HTTP + +## Encryption + +All three the protocol types above use TLS in one form or another to encrypt communications. Therefore the basics around encrypting a specific client to server communication is straightforward: + + * Server-side: + * Generate a CA private key and cert as the root for your certificate + hierarchy. + * (optionally) Generate intermediate keys to serve as signing + keys for your server certificates. We will not cover this case in + this document. + * Generate a private key for the server component involved. + * Generate a CSR using the private key. + * Use the CA key material and the CSR to generate/sign the server + certificate. + * Install the server cert and private key using the appropriate Vitess + options for the component in question. + * If required, adjust other Vitess component options to enforce/require + TLS-only communications. + +## Server authentication + +In addition to encrypting the connection, you may want or need to configure client-side server authentication. This is the process by which the client verifies that the server it is trying to establish a TLS connection to is who they claim to be, and not an imposter or man-in-the-middle. We achieve this by: + + * Client-side: + * Install the CA cert used by your certificate issuing process to sign the server component certificates. + * Adjust the Vitess client component options to verify the server certificate using the installed CA cert. This would typically involve specifying the CA cert, as well as the server or common name to expect from the server component, if it isn't the same as the DNS name (or has an IP SAN configured). + +## Client authentication + +Client authentication in Vitess can take two forms, depending on the protocol in question: + + * TLS client certificate authentication (also known as mTLS) + * Username/password authentication; this is only an option for the connections involving the MySQL protocol. + +## Walkthroughs + +We will now cover how to setup the various TLS component combinations. We will start with the data path, then move on to the control paths. We will handle [encryption](#encryption) and [server authentication](#server-authentication) together, and then handle [client authentication](#client-authentication) separately. + +### Certificate generation + +As discussed above, large organizations will often have established tools to secure a TLS certificate hierarchy and issue certificates. For the purpose of these walkthroughs, we could use bare `openssl` commands to step through every detail. However, since we consider this an implementation detail that is likely to vary from user to user, we will leverage a shell-script-based tool called [easy-rsa](https://github.com/OpenVPN/easy-rsa) that uses `openssl` under the covers, and hides much of the complexity. + +This tool has been around for many years as part of the OpenVPN project, and can perform all the steps to setup a CA, generate server certificates and also client certificates if desired. Since `easy-rsa` is just a set of shell scripts, if you require a closer understanding of how every step works, this is easy to discover as well. Lastly, `easy-rsa` can be used in production, and can easily manage thousands of certificates, if desired. + +We will use the newest `easy-rsa` release at the time of writing, version 3.0.8. + +### Installing easy-rsa + +Create a directory to install and run `easy-rsa` from, download and unpack the tool: + + ```bash + $ echo $HOME + /home/user + $ mkdir ~/CA + $ cd ~/CA/ + $ wget https://github.com/OpenVPN/easy-rsa/releases/download/v3.0.8/EasyRSA-3.0.8.tgz + . + . + 2020-10-02 16:10:22 (604 KB/s) - ‘EasyRSA-3.0.8.tgz’ saved [48907/48907] + $ tar zxf EasyRSA-3.0.8.tgz + $ mv EasyRSA-3.0.8/easyrsa . + $ mv EasyRSA-3.0.8/openssl-easyrsa.cnf . + $ mv EasyRSA-3.0.8/x509-types . + $ mv EasyRSA-3.0.8/vars.example vars + $ rm -rf EasyRSA-3.0.8 + ``` + +Edit the `vars` file appropriately for your setup. For the purposes of this walkthrough we will just append the following lines at the end of the file. Please adjust for your needs: + + ``` + set_var EASYRSA_DN "org" + set_var EASYRSA_REQ_COUNTRY "US" + set_var EASYRSA_REQ_PROVINCE "California" + set_var EASYRSA_REQ_CITY "Mountain View" + set_var EASYRSA_REQ_ORG "PlanetScale Inc" + set_var EASYRSA_REQ_EMAIL "carequest@planetscale.com" + set_var EASYRSA_REQ_OU "Operations" + set_var EASYRSA_KEY_SIZE 2048 + set_var EASYRSA_ALGO rsa + set_var EASYRSA_CA_EXPIRE 3650 + set_var EASYRSA_CERT_EXPIRE 1095 + ``` + +Bootstrap your CA. During the second step you will be prompted for a password. For the answers after the password prompt, you should be able to just hit enter multiple times as you have already configured it in the `vars` file above. + +{{< warning >}} +Do not forget this password! You will not be able to recover it. +{{< /warning >}} + +```bash + $ cd ~/CA/ + $ ./easyrsa init-pki + + Note: using Easy-RSA configuration from: /home/user/CA/vars + + init-pki complete; you may now create a CA or requests. + Your newly created PKI dir is: /home/user/CA/pki + + $ ./easyrsa build-ca + + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + + Enter New CA Key Passphrase: + Re-Enter New CA Key Passphrase: + Generating RSA private key, 2048 bit long modulus (2 primes) + ...............................................................................+++++ + e is 65537 (0x010001) + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [US]: + State or Province Name (full name) [California]: + Locality Name (eg, city) [Mountain View]: + Organization Name (eg, company) [PlanetScale Inc]: + Organizational Unit Name (eg, section) [Operations]: + Common Name (eg: your user, host, or server name) [Easy-RSA CA]: + Email Address [carequest@planetscale.com]: + + CA creation complete and you may now import and sign cert requests. + Your new CA certificate file for publishing is at: + /home/user/CA/pki/ca.crt +``` + +Your CA is now configured and you should be able to generate certs easily now. + +### Application to vtgate + +While applications can connect to vtgate using gRPC, the vast majority of Vitess users only use the MySQL protocol. When using the MySQL protocol, most users will use username/password for client authentication, although it is also possible to configure TLS client certificate authentication. We will assume the use of username/password authentication. + +For each vtgate you should generate a server private key and certificate. We will do this in two steps: + +- First we generate a private key and certificate request. +- We will then use the CA to sign that request to produce the server certificate. + +For the the prompts during `gen-req`, you can just hit enter. You will be prompted to type `yes` and enter the CA password during the `sign-req` phase. + +```bash + $ cd ~/CA/ + $ ./easyrsa gen-req vtgate1 nopass + + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + Generating a RSA private key + ............................+++++ + writing new private key to '/home/user/CA/pki/easy-rsa-178308.W6uc3G/tmp.Iqlvgf' + ----- + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [US]: + State or Province Name (full name) [California]: + Locality Name (eg, city) [Mountain View]: + Organization Name (eg, company) [PlanetScale Inc]: + Organizational Unit Name (eg, section) [Operations]: + Common Name (eg: your user, host, or server name) [vtgate1]: + Email Address [carequest@planetscale.com]: + + Keypair and certificate request completed. Your files are: + req: /home/user/CA/pki/reqs/vtgate1.req + key: /home/user/CA/pki/private/vtgate1.key + + $ ./easyrsa sign-req server vtgate1 + + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + + + You are about to sign the following certificate. + Please check over the details shown below for accuracy. Note that this request + has not been cryptographically verified. Please be sure it came from a trusted + source or that you have verified the request checksum with the sender. + + Request subject, to be signed as a server certificate for 1095 days: + + subject= + countryName = US + stateOrProvinceName = California + localityName = Mountain View + organizationName = PlanetScale Inc + organizationalUnitName = Operations + commonName = vtgate1 + emailAddress = carequest@planetscale.com + + + Type the word 'yes' to continue, or any other input to abort. + Confirm request details: yes + Using configuration from /home/user/CA/pki/easy-rsa-177552.IsttQK/tmp.NA5kv0 + Enter pass phrase for /home/user/CA/pki/private/ca.key: + Check that the request matches the signature + Signature ok + The Subject's Distinguished Name is as follows + countryName :PRINTABLE:'US' + stateOrProvinceName :ASN.1 12:'California' + localityName :ASN.1 12:'Mountain View' + organizationName :ASN.1 12:'PlanetScale Inc' + organizationalUnitName:ASN.1 12:'Operations' + commonName :ASN.1 12:'vtgate1' + emailAddress :IA5STRING:'carequest@planetscale.com' + Certificate is to be certified until Oct 4 00:07:58 2023 GMT (1095 days) + + Write out database with 1 new entries + Data Base Updated + + Certificate created at: /home/user/CA/pki/issued/vtgate1.crt +``` + +Our certificate has now been issued, and we can use the private key file in `/home/user/CA/pki/private/vtgate1.key` along with the issued server certificate in `/home/user/CA/pki/issued/vtgate1.crt` to configure vtgate for using TLS with MySQL clients. First we copy the private key and server certificate to the appropriate configuration directory, and then tighten up the file permissions and ownership. + +This will differ in your environment: + +```bash + $ mkdir ~/config/ + $ cp /home/user/CA/pki/private/vtgate1.key ~/config/ + $ cp /home/user/CA/pki/issued/vtgate1.crt ~/config/ + $ chown vtgate:vtgate ~/config/vtgate1.* + $ chmod 400 ~/config/vtgate1.* +``` + +Now, we can add the options to vtgate to use the above private key and server certificate. Modify the vtgate commandline or startup script to add the following parameters: + +``` + --mysql_server_ssl_key ~/config/vtgate1.key --mysql_server_ssl_cert ~/config/vtgate1.crt --mysql_server_require_secure_transport +``` + +{{< info >}} +You can now start/restart the vtgate instance. Any vtgate connections from now on will be required to use TLS, so you may have to reconfigure your applications/clients. In addition, to avoid man-in-the-middle attacks, you may want the clients to verify the server by validating the server certificate against the CA cert. +{{< /info >}} + +Here is an example using the MySQL CLI client. Exact options will vary between MySQL versions, this is using MySQL (8.0.21) client: + +```bash + $ cp /home/user/CA/pki/ca.crt /var/tmp/ca.crt + $ mysql -u mysql_user -p -h 127.0.0.1 -P 15306 --ssl-mode=VERIFY_CA --ssl-ca=/var/tmp/ca.crt + Enter password: + Welcome to the MySQL monitor. Commands end with ; or \g. + Your MySQL connection id is 3 + Server version: 5.7.9-Vitess MySQL Community Server - GPL + . + . + . + mysql> \s + -------------- + mysql Ver 8.0.20-11 for Linux on x86_64 (Percona Server (GPL), Release 11, Revision 159f0eb) + + Connection id: 3 + Current database: + Current user: vt_app@localhost + SSL: Cipher in use is ECDHE-RSA-AES128-GCM-SHA256 + Current pager: stdout + Using outfile: '' + Using delimiter: ; + Server version: 5.7.9-Vitess MySQL Community Server - GPL + Protocol version: 10 + Connection: 127.0.0.1 via TCP/IP + . + . +``` + +The above MySQL CLI output shows that the connection is encrypted, and that the server (vtgate) was successfully validated using the CA certificate. If the server certificate could not be validated using the CA certificate, an error similar to this would have been seen: + +``` + ERROR 2026 (HY000): SSL connection error: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed +``` + +If TLS was not setup on the vtgate at all, an error like this could have resulted: + +``` + ERROR 2026 (HY000): SSL connection error: SSL is required but the server doesn't support it +``` + +### vttablet to MySQL + +A common Vitess deployment model is to co-locate vttablet and MySQL on the same host/VM/container. In a case like this, vttablet connectivity to MySQL will be via local unix socket or TCP connection on localhost. It is unnecessary to configure encryption between vttablet and MySQL in this case, since the traffic never leaves the local machine/VM. However, in some deployment models vttablet and MySQL are running on different hosts, and you may want vttablet to use TLS to speak to MySQL. + +We will not cover configuring MySQL to use TLS certificates extensively here, just the minimum. Please consult the MySQL documentation for further information. Again, we will also assume that vttablet will be using MySQL username/password client authentication. + +Note that when you are configuring TLS and MySQL you will need to be aware of what TLS versions are supported. You may be using an [older version of MySQL that does not have TLS 1.2 support](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_MySQL.html#MySQL.Concepts.SSLSupport). If you need to support pre 1.2 TLS [vtgate supports ](https://github.com/vitessio/vitess/blob/de7f133dbe2dd6a7910f13c682910a4f5c0ac0df/go/vt/vtgate/plugin_mysql_server.go#L67)that setting using `--mysql_server_tls_min_version` and vttablet supports that setting using `--db_tls_min_version=TLSv1.1` + +Generate a server certificate for our MySQL instance using our CA: + +```bash + $ cd ~/CA/ + $ ./easyrsa gen-req mysql1 nopass + . + . + . + Keypair and certificate request completed. Your files are: + req: /home/user/CA/pki/reqs/mysql1.req + key: /home/user/CA/pki/private/mysql1.key + + $ ./easyrsa sign-req server mysql1 + . + . + . + Write out database with 1 new entries + Data Base Updated + + Certificate created at: /home/user/CA/pki/issued/mysql1.crt +``` + +Copy the files `/home/user/CA/pki/private/mysql1.key` and `/home/user/CA/pki/issued/mysql1.crt` to the MySQL server in the appropriate locations, securing their ownership and permissions appropriately. + +Configure the MySQL server options `ssl-key` and `ssl-cert` appropriately to point to where you placed the private key and certificate above. You can read more about it [here](https://dev.mysql.com/doc/mysql-security-excerpt/8.0/en/using-encrypted-connections.html) + +Note that these options do not require clients to use TLS, but is optional. If you need to require all TCP/IP clients to use TLS, you can use the MySQL server option `require_secure_transport`, or you can enforce it on a per MySQL user basis by using the `REQUIRE SSL` option when creating or altering a MySQL-level user. See the MySQL documentation for details. + +Restart your MySQL server to make these MySQL server option configuration changes active. + +Now, configure vttablet to connect to MySQL using the necessary parameters, verifying the CA certificate: + +```bash + $ cp /home/user/CA/pki/ca.crt ~/config/ +``` + +Add the vttablet parameters: + +``` + --db_ssl_ca /home/user/config/ca.crt --db_flags 1073743872 --db_server_name mysql1 +``` + +Restart the vttablet. Note that the `db_server_name` parameter value will differ depending on your issued certificate common name; and is unnecessary if the certificate common name matches the DNS name vttablet is using to connect to the MySQL server. + +The `1073743872` is a combination of the MySQL `CLIENT_SSL` (2048) and `CLIENT_SSL_VERIFY_SERVER_CERT` flags (1073741824); which means "encrypt the connection to MySQL *and* verify the SSL cert presented by the server". + +If you just wish to encrypt the vttablet -> MySQL server communication and you do not care about server certificate validation, you can just use this vttablet flag instead: + +``` + --db_flags 2048 +``` + +Note that using the above `db_flags` will also result in the MySQL to MySQL communication for replication between the replica/rdonly instances of a Vitess shard and its primary to be encrypted, as long as the upstream MySQL instance the replica is connecting to has been configured correctly to support TLS MySQL protocol connections (see above). + +## vttablet data and control paths + +In Vitess, communication between vtgate and vttablet instances are via gRPC. gRPC uses HTTP/2 as a transport protocol, but by default this is not encrypted in Vitess. To secure this data path you need to, at a minimum, configure TLS for gRPC on the server (vttablet) side. + +Other components, as detailed above, also connect to vttablet via gRPC. After configuring vttablet gRPC for TLS, you will need to configure all these components (vtgate, other vttablets, vtctld) explicitly to connect using TLS to vttablet via gRPC, or you will have a partially or wholly non-functional system. + +#### vtgate to vttablet + +First, generate a certificate for use by vttablet: + +```bash + $ cd ~/CA/ + $ ./easyrsa gen-req vttablet1 nopass + + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + Generating a RSA private key + ..................................+++++ + .....+++++ + writing new private key to '/home/user/CA/pki/easy-rsa-209692.tdDNNt/tmp.hwhw8x' + ----- + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [US]: + State or Province Name (full name) [California]: + Locality Name (eg, city) [Mountain View]: + Organization Name (eg, company) [PlanetScale Inc]: + Organizational Unit Name (eg, section) [Operations]: + Common Name (eg: your user, host, or server name) [vttablet1]: + Email Address [carequest@planetscale.com]: + + Keypair and certificate request completed. Your files are: + req: /home/user/CA/pki/reqs/vttablet1.req + key: /home/user/CA/pki/private/vttablet1.key + + $ ./easyrsa sign-req server vttablet1 + + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + + + You are about to sign the following certificate. + Please check over the details shown below for accuracy. Note that this request + has not been cryptographically verified. Please be sure it came from a trusted + source or that you have verified the request checksum with the sender. + + Request subject, to be signed as a server certificate for 1095 days: + + subject= + countryName = US + stateOrProvinceName = California + localityName = Mountain View + organizationName = PlanetScale Inc + organizationalUnitName = Operations + commonName = vttablet1 + emailAddress = carequest@planetscale.com + + + Type the word 'yes' to continue, or any other input to abort. + Confirm request details: yes + Using configuration from /home/user/CA/pki/easy-rsa-209844.f9wDrk/tmp.3rww6R + Enter pass phrase for /home/user/CA/pki/private/ca.key: + Check that the request matches the signature + Signature ok + The Subject's Distinguished Name is as follows + countryName :PRINTABLE:'US' + stateOrProvinceName :ASN.1 12:'California' + localityName :ASN.1 12:'Mountain View' + organizationName :ASN.1 12:'PlanetScale Inc' + organizationalUnitName:ASN.1 12:'Operations' + commonName :ASN.1 12:'vttablet1' + emailAddress :IA5STRING:'carequest@planetscale.com' + Certificate is to be certified until Oct 4 20:23:48 2023 GMT (1095 days) + + Write out database with 1 new entries + Data Base Updated + + Certificate created at: /home/user/CA/pki/issued/vttablet1.crt + + $ cp /home/user/CA/pki/private/vttablet1.key ~/config/ + $ cp /home/user/CA/pki/issued/vttablet1.crt ~/config/ + $ chmod 400 ~/config/vttablet1.* +``` + +To configure vttablet to use a server certificate for its gRPC server, add the below to the vttablet parameters: + +``` + --grpc_cert /home/user/config/vttablet1.crt --grpc_key /home/user/config/vttablet1.key +``` + +Note that adding these options **enforces** TLS only gRPC connections to this vttablet instace from that point onwards. + +This means that you will need to add the following option to your vtgate instances to successfully connect to this vttablet instance from this point forward: + +``` + --tablet_grpc_server_name vttablet1 --tablet_grpc_ca /home/user/config/ca.crt +``` + +Adding this option to a vtgate instance will require all vttablet instances this vtgate connects to to be configured for TLS as well. This is unfortunately an all-or-nothing proposition, there is no incremental migration to using TLS in this case. + +If you have vtgate instances accessing your vttablet instance after you have configured TLS on the vttablet side, you may see errors like this in the vttablet logs: + +``` + W1004 13:34:16.352458 212354 server.go:650] grpc: Server.Serve failed to complete security handshake from "[::1]:51492": tls: first record does not look like a TLS handshake +``` + +Conversely, if you have configured the TLS parameters on the vtgate side and the vtgate instance is still trying to connect to vttablet instances that are not configured with the correct TLS options, you might see errors like this in the vtgate logs: + +``` + W1004 14:38:29.383672 214179 tablet_health_check.go:323] tablet cell:"zone1" uid:101 healthcheck stream error: Code: UNAVAILABLE + vttablet: rpc error: code = Unavailable desc = all SubConns are in TransientFailure, latest connection error: connection error: desc = "transport: authentication handshake failed: tls: first record does not look like a TLS handshake" +``` + +In case of VTOrc, you will need to add following to VTOrc instance to successfully connect to this vttablet instance + +``` + --tablet_manager_grpc_server_name vttablet1 --tablet_manager_grpc_ca /home/user/config/ca.crt +``` + +#### vttablet to vtablet: vreplication within or across shards + +For vreplication to work between vttablet instances once the gRPC server TLS options above are activated, you will need to add the following additional vttablet options: + +``` + --tablet_grpc_server_name vttablet1 --tablet_grpc_ca /home/user/config/ca.crt +``` + +Since each vttablet instance may need to talk to more than one other vttablet instances for vreplication streams, the implication is that each vttablet instances needs to either: + + * Use the same vttablet server key material and server certificate common name for each vttablet instance. This is obviously the easiest option, but might not conform to your compliance requirements. + * or, ensure each vttablet server certificate common name or IP SAN matches the DNS name or IP it it accessed via. In this case, you can omit the use of the `--tablet_grpc_server_name` above for vttablet, and also for vtgate. + +#### vtctld to vttablet + +Once your vttablet(s) are configured with gRPC server TLS options as above, +you will need to also add TLS client options to vtctld, or vtctld will be +unable to connect to your vttablet(s). + +* To achieve this, add the following options to the vtctld commandline: + +``` + --tablet_grpc_server_name vttablet1 --tablet_grpc_ca /home/user/config/ca.crt --tablet_manager_grpc_server_name vttablet1 --tablet_manager_grpc_ca /home/user/config/ca.crt +``` + +### vtctldclient to vtctld + +The communication from vtctldclient to vtctld is also via gRPC, so the method for securing it is similar to vtctld to vttablet above. + +Generate a server certificate for vtctld: + +```bash + $ cd ~/CA/ + $ ./easyrsa gen-req vtctld1 nopass + + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + Generating a RSA private key + ..................................................+++++ + ....................................................+++++ + writing new private key to '/home/user/CA/pki/easy-rsa-234817.QW1l8f/tmp.REK9r3' + ----- + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [US]: + State or Province Name (full name) [California]: + Locality Name (eg, city) [Mountain View]: + Organization Name (eg, company) [PlanetScale Inc]: + Organizational Unit Name (eg, section) [Operations]: + Common Name (eg: your user, host, or server name) [vtctld1]: + Email Address [carequest@planetscale.com]: + + Keypair and certificate request completed. Your files are: + req: /home/user/CA/pki/reqs/vtctld1.req + key: /home/user/CA/pki/private/vtctld1.key + + $ ./easyrsa sign-req server vtctld1 + + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + + + You are about to sign the following certificate. + Please check over the details shown below for accuracy. Note that this request + has not been cryptographically verified. Please be sure it came from a trusted + source or that you have verified the request checksum with the sender. + + Request subject, to be signed as a server certificate for 1095 days: + + subject= + countryName = US + stateOrProvinceName = California + localityName = Mountain View + organizationName = PlanetScale Inc + organizationalUnitName = Operations + commonName = vtctld1 + emailAddress = carequest@planetscale.com + + + Type the word 'yes' to continue, or any other input to abort. + Confirm request details: yes + Using configuration from /home/user/CA/pki/easy-rsa-234873.8zKYwl/tmp.zDGxDd + Enter pass phrase for /home/user/CA/pki/private/ca.key: + Check that the request matches the signature + Signature ok + The Subject's Distinguished Name is as follows + countryName :PRINTABLE:'US' + stateOrProvinceName :ASN.1 12:'California' + localityName :ASN.1 12:'Mountain View' + organizationName :ASN.1 12:'PlanetScale Inc' + organizationalUnitName:ASN.1 12:'Operations' + commonName :ASN.1 12:'vtctld1' + emailAddress :IA5STRING:'carequest@planetscale.com' + Certificate is to be certified until Oct 5 02:30:05 2023 GMT (1095 days) + + Write out database with 1 new entries + Data Base Updated + + Certificate created at: /home/user/CA/pki/issued/vtctld1.crt + + $ cp /home/user/CA/pki/issued/vtctld1.crt ~/config/ + $ cp /home/user/CA/pki/private/vtctld1.key ~/config/ +``` + +Add TLS gRPC server options to vtctld commandline and restart vtctld: + +``` + --grpc_cert /home/user/config/vtctld1.crt --grpc_key /home/user/config/vtctld1.key +``` + +At this point, all vtctldclient connections to vtctld will need the appropriate additional TLS gRPC options, or they will fail. Add these options: + +``` + --vtctld_grpc_ca /home/user/config/ca.crt --vtctld_grpc_server_name vtctld1 +``` + +## Topology server data paths + +Vitess supports several topology server implementations, with the major ones being `etcd` and `ZooKeeper`. Since each of these use their own protocols, securing communications between Vitess components (like vtgate, vttablet and vtctld) and the topology server is specific to the topology server implementation. We we will cover `etcd` first, then `ZooKeeper`. + +It should be noted that regardless of the implementation, no sensitive data is stored in the Vitess topology server, i.e.: + + * No data (queries/results) is stored in, or flows through, the topology server. + * No secrets (keys, certificates, passwords) are stored in the toplogy server + data store. + * Only metadata (VSchema, keyspace and shard information) is stored in the + topology server data store. + +### Configuring etcd for secure connections + +We will not cover setting up `etcd` with certificates in this guide. You can consult the `etcd` documenation [here](https://etcd.io/docs/v3.5/op-guide/security/). Note that you can use `easy-rsa` as above to generate your server private key and certificate pairs. If you do not require client authentication, that is sufficient, and you then just have to distribute your CA certificate (`/home/user/CA/pki/ca.crt` in the examples above) to your clients, and proceed as in the next section. + +### Configuring secure connectivity between vtgate/vttablet/vtctld and etcd + +The Vitess servers (vtgate/vttablet/vtctld) share the same set of parameters to connect via TLS to `etcd`: + + * `--topo_etcd_tls_ca` : Path to the PEM certificate used to authenticate the TLS CA certificate presented by the `etcd` server. Enables TLS to `etcd` if present. + * `--topo_etcd_tls_cert` : Path to a PEM client certificate (mTLS) used to authenticate this client to the `etcd` server. Only necessary if your `etcd` server requires client authentication. + * `--topo_etcd_tls_key` : Path to a PEM private key used for signing the client certificate (mTLS) exchange with the `etcd` server. Only necessary if your `etcd` server requires client authentication. + +As is necessary for your design/architecture, add one or more of the above options to your vtgate, vttablet and vtctld instances. + +### Configuring etcd for secure connections + +We will just mention the basic flags here for getting `etcd` to accept encrypted client connections. We will not cover the flags to make sure that communication between `etcd` cluster members (peers) are encrypted. + +Flags: + + * `--listen-client-urls`: specify an `https://` host and port prefix + * `--advertise-client-urls`: specify an `https://` host and port prefix + * `--cert-file`: Point to to a server cert PEM file + * `--key-file`: Point to to a server key PEM file + * (optional) `--cipher-suites`: Can be used to limit the cipher suites the etc server will negotiate (e.g. `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` is a popular combination). + +Note that the Vitess client components will negotiate any of the standard golang TLS client cipher suites (which can vary somewhat depending on which golang version Vitess was compiled with, and what libraries are available on the platform). It is not possible to limit the cipher suites from the etcd client (i.e. Vitess) components. + +It is also possible to configure `etcd` to require/verify client certificates from the clients; for that use the `--trusted-ca-file` option to point to the PEM CA cert that the client certs are signed with. + +### Configuring ZooKeeper for secure connections + +We will not cover setting up `Zookeeper` with certificates in this guide. You can consult the `Zookeeper` documenation [here](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+SSL+User+Guide), specifically the `Server` section. Note that you can use `easy-rsa` as above to generate your server private key and certificate pairs. If you do not require client authentication, that is sufficient, and you then just have to distribute your CA certificate (`/home/user/CA/pki/ca.crt` in the examples above) to your clients, and proceed as in the next section. + +### Configuring secure connectivity between vtgate/vttablet/vtctld and ZooKeeper + +The Vitess servers (vtgate/vttablet/vtctld) share the same set of parameters to connect via TLS to `Zookeeper`: + + * `--topo_zk_tls_ca` : Path to the PEM certificate used to authenticate the TLS CA certificate presented by the `Zookeeper` server. Enables TLS to `etcd` if present. + * `--topo_zk_tls_cert` : Path to a PEM client certificate (mTLS) used to authenticate this client to the `Zookeeper` server. Only necessary if your `Zookeeper` server requires client authentication. + * `--topo_zk_tls_key` : Path to a PEM private key used for signing the client certificate (mTLS) exchange with the `Zookeeper` server. Only necessary if your `Zookeeper` server requires client certificate authentication. + * `--topo_zk_auth_file` : Unlike `etcd`, `Zookeeper` also supports username/password authentication from clients. This option is used to pass the combination of authentication schema, username and password to the client to connect with to the server, e.g. with a value like `digest:username:password`. + +As is necessary for your design/architecture, add one or more of the above options to your vtgate, vttablet and vtctld instances. + +## Generating client certificates with easy-rsa + +`easy-rsa` can also be used to generate client certificates (i.e for mTLS or mutual TLS). Mutual TLS needs at least two additional parameters on the client side, and one additional parameter on the server side: + + * Client side: + * Private key to sign the client certificate exchange with server. + * Client certificate itself. + * Server side: + * CA certificate that signed the client certificate(s) that the client(s) are presenting. + +To generate the client-side private and client certificate using `easy-rsa`: + +```bash + $ cd ~/CA/ + $ ./easyrsa gen-req client1 nopass + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + Generating a RSA private key + ..........+++++ + .........+++++ + writing new private key to '/home/user/CA/pki/easy-rsa-144133.y9mHHP/tmp.LSLIhv' + ----- + You are about to be asked to enter information that will be incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [US]: + State or Province Name (full name) [California]: + Locality Name (eg, city) [Mountain View]: + Organization Name (eg, company) [PlanetScale Inc]: + Organizational Unit Name (eg, section) [Operations]: + Common Name (eg: your user, host, or server name) [client1]: + Email Address [carequest@planetscale.com]: + + Keypair and certificate request completed. Your files are: + req: /home/user/CA/pki/reqs/client1.req + key: /home/user/CA/pki/private/client1.key + + $ ./easyrsa sign-req client client1 + Note: using Easy-RSA configuration from: /home/user/CA/vars + Using SSL: openssl OpenSSL 1.1.1g FIPS 21 Apr 2020 + + + You are about to sign the following certificate. + Please check over the details shown below for accuracy. Note that this request + has not been cryptographically verified. Please be sure it came from a trusted + source or that you have verified the request checksum with the sender. + + Request subject, to be signed as a client certificate for 1095 days: + + subject= + countryName = US + stateOrProvinceName = California + localityName = Mountain View + organizationName = PlanetScale Inc + organizationalUnitName = Operations + commonName = client1 + emailAddress = carequest@planetscale.com + + + Type the word 'yes' to continue, or any other input to abort. + Confirm request details: yes + Using configuration from /home/user/CA/pki/easy-rsa-144332.6AjhHm/tmp.KWRj4O + Enter pass phrase for /home/user/CA/pki/private/ca.key: + Check that the request matches the signature + Signature ok + The Subject's Distinguished Name is as follows + countryName :PRINTABLE:'US' + stateOrProvinceName :ASN.1 12:'California' + localityName :ASN.1 12:'Mountain View' + organizationName :ASN.1 12:'PlanetScale Inc' + organizationalUnitName:ASN.1 12:'Operations' + commonName :ASN.1 12:'client1' + emailAddress :IA5STRING:'carequest@planetscale.com' + Certificate is to be certified until Oct 14 04:10:28 2023 GMT (1095 days) + + Write out database with 1 new entries + Data Base Updated + + Certificate created at: /home/user/CA/pki/issued/client1.crt +``` + +Our client certificate and key has now been issued, and we can use the files `/home/user/CA/pki/issued/client1.crt` and `/home/user/CA/pki/private/client1.key` on our client for client certificate (mTLS) authentication. 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 new file mode 100644 index 000000000..af896cf22 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/unmanaged-tablet.md @@ -0,0 +1,177 @@ +--- +title: Unmanaged Tablet +weight: 45 +aliases: ['/docs/user-guides/unmanaged-tablet/'] +--- + +{{< info >}} +This guide follows on from the [local](../../../get-started/local) installation guide. +{{< /info >}} + +This guide uses the Vitess components vtctld, Topology Service and VTGate which have already been started in the local installation guide. It assumes that you have an existing MySQL Server setup that you would like to add to Vitess as a new keyspace, which we will call `legacy`. The same set of steps can be used to create a tablet that uses Amazon RDS, AWS Aurora, or Google CloudSQL. + +## Ensure all components are up + +You should have previously executed `./101_initial_cluster.sh` in the get-started guide. This will ensure that you have a Topology Service, vtgate, vtctld. For the unmanaged MySQL instance, I will be using an instance running on `127.0.0.1:5726`: + +```bash +source ../common/env.sh + +# verify vtgate/vitess is up and running +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 +$ source ../common/env.sh + +$ # verify vtgate/vitess is up and running +$ mysql commerce -e 'show tables' ++-----------------------+ +| Tables_in_vt_commerce | ++-----------------------+ +| corder | +| customer | +| product | ++-----------------------+ +$ # 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. ++------------------+ +| Tables_in_legacy | ++------------------+ +| legacytable | ++------------------+ +``` + +## Start a tablet to correspond to legacy + +The variables `TOPOLOGY_FLAGS` and `VTDATAROOT` should already be in the environment from sourcing env.sh earlier. We will call the new tablet UID 401. + +```bash +mkdir -p $VTDATAROOT/vt_0000000401 +vttablet \ + $TOPOLOGY_FLAGS \ + --logtostderr \ + --log_queries_to_file $VTDATAROOT/tmp/vttablet_0000000401_querylog.txt \ + --tablet-path "zone1-0000000401" \ + --init_keyspace legacy \ + --init_shard 0 \ + --init_tablet_type replica \ + --port 15401 \ + --grpc_port 16401 \ + --service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updatestream' \ + --pid_file $VTDATAROOT/vt_0000000401/vttablet.pid \ + --db_host 127.0.0.1 \ + --db_port 5726 \ + --db_app_user msandbox \ + --db_app_password msandbox \ + --db_dba_user msandbox \ + --db_dba_password msandbox \ + --db_repl_user msandbox \ + --db_repl_password msandbox \ + --db_filtered_user msandbox \ + --db_filtered_password msandbox \ + --db_allprivs_user msandbox \ + --db_allprivs_password msandbox \ + --init_db_name_override legacy \ + --init_populate_metadata \ + --disable_active_reparents & +``` + +Note that if your tablet is using a MySQL instance type where you do not have `SUPER` privileges to the database +(e.g. AWS RDS, AWS Aurora or Google CloudSQL), you should omit the `--init_populate_metadata` flag. The `--init_populate_metadata` flag should only be enabled if the cluster is being managed through Vitess. + +You should be able to see debug information written to screen confirming Vitess can reach the unmanaged server. A common problem is that you may need to change the authentication plugin to `mysql_native_password` (MySQL 8.0). + +Assuming that there are no errors, after a few seconds you can mark the server as externally promoted to primary: + +```bash +vtctldclient TabletExternallyReparented zone1-401 +``` + +## Connect via VTGate + +VTGate should now be able to route queries to your unmanaged MySQL server: + +```bash +$ mysql legacy -e 'show tables' ++------------------+ +| Tables_in_legacy | ++------------------+ +| legacytable | ++------------------+ +``` + +You can even join between the unmanaged tablet and the managed tablets. Vitess will execute the query as a scatter-gather: + +```sql +mysql> use commerce; +Database changed + +mysql> select corder.order_id from corder inner join legacy.legacytable on corder.order_id=legacy.legacytable.id; +Empty set (0.01 sec) +``` + +## Move legacytable to the commerce keyspace + +Move the table: +```bash +vtctlclient MoveTables -- --source legacy --tables 'legacytable' Create commerce.legacy2commerce +``` +
    +Monitor the workflow: + +use `Show` or `Progress` +```bash +vtctlclient MoveTables -- Show commerce.legacy2commerce +vtctlclient MoveTables -- Progress commerce.legacy2commerce +``` + +You can also use the [`Workflow show`](../../../reference/vreplication/workflow/) command to get the progress as it has much more info as well. + +```bash +vtctlclient Workflow commerce.legacy2commerce show +``` +
    Switch traffic: +```bash +vtctlclient MoveTables -- --tablet_type=rdonly,replica SwitchTraffic commerce.legacy2commerce +``` +
    Complete the `MoveTables`: +```bash +vtctlclient MoveTables Complete commerce.legacy2commerce +``` +
    Verify that the table was moved: +```bash +source ../common/env.sh + +# verify vtgate/vitess is up and running +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 +$ source ../common/env.sh +$ +$ # verify vtgate/vitess is up and running +$ mysql commerce -e 'show tables' ++-----------------------+ +| Tables_in_vt_commerce | ++-----------------------+ +| corder | +| customer | +| legacytable | +| product | ++-----------------------+ +$ # 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-advanced/user-management.md b/content/en/docs/19.0/user-guides/configuration-advanced/user-management.md new file mode 100644 index 000000000..f48c9937b --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-advanced/user-management.md @@ -0,0 +1,23 @@ +--- +title: User Management and Authentication +weight: 1 +aliases: ['/docs/user-guides/user-management/'] +--- + +Vitess uses its own mechanism for managing users and their permissions through + VTGate. As a result, the `CREATE USER....` and +`GRANT...` statements will not work if sent through VTGate. + +## Authentication + +The Vitess VTGate component takes care of authentication for requests so we +will need to add any users that should have access to the Keyspaces via the +command-line options to VTGate. + +VTGate supports multiple types of authentication: + +* none - No authentication is performed. This is the default. +* static - [File-based authentication](../static-auth) +* ldap - [LDAP-based authentication](../ldap_auth) +* clientcert - TLS client certificate-based authentication +* vault - Vault-based authentication diff --git a/content/en/docs/19.0/user-guides/configuration-basic/_index.md b/content/en/docs/19.0/user-guides/configuration-basic/_index.md new file mode 100644 index 000000000..12898272a --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/_index.md @@ -0,0 +1,5 @@ +--- +title: Running in Production +description: Instructions and guidelines for running Vitess in a production environment +weight: 2 +--- diff --git a/content/en/docs/19.0/user-guides/configuration-basic/add-delete-cell.md b/content/en/docs/19.0/user-guides/configuration-basic/add-delete-cell.md new file mode 100644 index 000000000..786d197a3 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/add-delete-cell.md @@ -0,0 +1,48 @@ +--- +title: Add or Delete a Cell +weight: 15 +--- + +## Add +To add a cell after a cluster is up and running, you start off by creating one using the same steps previously performed to create the first cell: + +```sh +vtctldclient AddCellInfo \ + --root /vitess/cell2 \ + --server-address \ + cell2 +``` + +Additionally, you will need to make the keyspace info visible in the cell. For every keyspace, issue the following: + +```text +vtctldclient RebuildKeyspaceGraph --cells=cell2 +``` + +And finally, deploy the VSchema with + +```text +vtctldclient RebuildVSchemaGraph --cells=cell2 +``` + +{{< info >}} +If the `cells` option is not specified, the rebuild deploys to all cells. +{{< /info >}} + +Once these steps are done, you can bring up the necessary MySQLs, vttablets and vtgates under that cell. + +## Delete + +To delete a cell, bring down all servers in that cell, and then remove its entry from the global topo with: + +``` +vtctldclient DeleteCellInfo --force cell2 +``` + +If `--force` is not used the command will error out if any keyspace was deployed to that cell. There is currently no clean way to undeploy a keyspace from a cell. So, `--force` will need to be used for most use cases. + +VTGates and vtctlds do not refresh themselves after a cell is deleted or updated. It is recommended that you restart them. + +Once the Vitess components are restarted, the final step will be to bring down the cell-specific topo server. + +If you had deployed a cell-specific toposerver, that can now be brought down. The deployed info under the cell's root (`/vitess/cell2`) will not be automatically deleted. You will have to manually delete that directory. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/backups-restores.md b/content/en/docs/19.0/user-guides/configuration-basic/backups-restores.md new file mode 100644 index 000000000..7f537078f --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/backups-restores.md @@ -0,0 +1,32 @@ +--- +title: Backups and Restores +weight: 12 +--- + +The default settings created by `mysqlctl` set the binlog `expire_logs_days` to 3. Once the binlogs expire, you will not be able to bring up new empty replicas that can catch up to the current state. + +So, you need to take regular backups, probably through a cron job. Assuming that you’ve configured the shared storage and provided the correct parameters to the Vitess components, you should be able to create a backup as follows: + +```text +vtctldclient Backup cell1-101 +``` + +{{< warning >}} +If you are not using an online backup method like xtrabackup, the `Backup` command will shut down the MySQL instance to perform the operation. The instance will be unavailable until the backup is finished, the restarted MySQL instance is pointed back at the primary and caught up on replication. +{{< /warning >}} + +{{< info >}} +It is recommended that you also periodically backup your binlogs. Vitess does not natively support this ability. You will need to set this up yourself. +{{< /info >}} + +Once a backup is taken, bringing up a subsequent vttablet-MySQL pair will cause it to restore from the backup instead of starting with a fresh MySQL instance. This will make it catch up from the beginning of time. You should see the following messages in the vttablet logs: + +```text +I0102 13:06:01.379759 30842 backup.go:227] Restore: looking for a suitable backup to restore +I0102 13:06:01.379820 30842 shard_sync.go:70] Change to tablet state +I0102 13:06:01.380757 30842 backupengine.go:221] Restore: found backup commerce/0 2021-01-02.205158.cell1-0000000101 to restore +``` + +If a MySQL with existing data is restarted either manually or due to a failure, an automatic restore will not be performed. Instead, a recovery will be performed from the existing data files. + +Please refer to the [Backup and Restore](../../operating-vitess/backup-and-restore) documentation for more information. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/collations.md b/content/en/docs/19.0/user-guides/configuration-basic/collations.md new file mode 100644 index 000000000..880a1fa1e --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/collations.md @@ -0,0 +1,414 @@ +--- +title: Collations and Character sets +description: +weight: 1 +--- + +MySQL is a Unicode-aware database, and as explained on [the MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/charset-mysql.html), it supports using many different character sets to store textual data in databases, and many different collations which are used to compare and sort this textual data. + +Likewise, Vitess is also Unicode-aware, and it supports the vast majority of the collations and charsets in the underlying MySQL server. On a basic level, this support means that Vitess handles gracefully textual Unicode columns and queries, and relays this information to MySQL clients without losing or corrupting the encoding of the data. On top of this, newer versions of Vitess are also capable of performing textual comparison and sorting operations in SQL queries directly on VTGate instances, greatly speeding up complex operations such as cross-shard joins. + +### Supported collations + +The collation environment (i.e. the set of support collations and charsets) of a Vitess cluster is defined by the MySQL server version flag (`--mysql_server_version`) provided to the VTGate and VTTablet instances in the cluster. Higher (newer) MySQL versions will enable built-in support for more collations. + +The following table lists all of the supported collations in the current release of Vitess: + +| Legend | | +|----|----| +| ✅ | Vitess has full support for this collation. | +| ⚠️ | The underlying MySQL (or compatible) database supports this collation, but Vitess does not. | +| ❌ | Neither Vitess nor the underlying MySQL database supports this collation. | + +Using collations that are not supported by Vitess but implemented in the underlying MySQL instance can lead to unpredictable behavior. + +| Collation | Charset | MySQL 8.0 | MySQL 5.7 | MySQL 5.6 | MariaDB 10.3 | MariaDB 10.2 | MariaDB 10.1 | MariaDB 10.0 | +|---|---|---|---|---|---|---|---|---| +| big5_chinese_ci | big5 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| latin2_czech_cs | latin2 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| dec8_swedish_ci | dec8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp850_general_ci | cp850 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_german1_ci | latin1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| hp8_english_ci | hp8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| koi8r_general_ci | koi8r | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_swedish_ci | latin1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin2_general_ci | latin2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| swe7_swedish_ci | swe7 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ascii_general_ci | ascii | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ujis_japanese_ci | ujis | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| sjis_japanese_ci | sjis | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1251_bulgarian_ci | cp1251 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_danish_ci | latin1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| hebrew_general_ci | hebrew | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| tis620_thai_ci | tis620 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| euckr_korean_ci | euckr | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin7_estonian_cs | latin7 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin2_hungarian_ci | latin2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| koi8u_general_ci | koi8u | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1251_ukrainian_ci | cp1251 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| gb2312_chinese_ci | gb2312 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| greek_general_ci | greek | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1250_general_ci | cp1250 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin2_croatian_ci | latin2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| gbk_chinese_ci | gbk | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| cp1257_lithuanian_ci | cp1257 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin5_turkish_ci | latin5 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_german2_ci | latin1 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| armscii8_general_ci | armscii8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_general_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1250_czech_cs | cp1250 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| ucs2_general_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp866_general_ci | cp866 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| keybcs2_general_ci | keybcs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| macce_general_ci | macce | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| macroman_general_ci | macroman | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp852_general_ci | cp852 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin7_general_ci | latin7 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin7_general_cs | latin7 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| macce_bin | macce | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1250_croatian_ci | cp1250 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_general_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_bin | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_bin | latin1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_general_ci | latin1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_general_cs | latin1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1251_bin | cp1251 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1251_general_ci | cp1251 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1251_general_cs | cp1251 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| macroman_bin | macroman | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_general_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_bin | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16le_general_ci | utf16le | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1256_general_ci | cp1256 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1257_bin | cp1257 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1257_general_ci | cp1257 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_general_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_bin | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16le_bin | utf16le | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| binary | binary | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| armscii8_bin | armscii8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ascii_bin | ascii | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1250_bin | cp1250 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1256_bin | cp1256 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp866_bin | cp866 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| dec8_bin | dec8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| greek_bin | greek | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| hebrew_bin | hebrew | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| hp8_bin | hp8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| keybcs2_bin | keybcs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| koi8r_bin | koi8r | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| koi8u_bin | koi8u | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_tolower_ci | utf8 | ⚠️ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| latin2_bin | latin2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin5_bin | latin5 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin7_bin | latin7 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp850_bin | cp850 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp852_bin | cp852 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| swe7_bin | swe7 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_bin | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| big5_bin | big5 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| euckr_bin | euckr | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| gb2312_bin | gb2312 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| gbk_bin | gbk | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| sjis_bin | sjis | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| tis620_bin | tis620 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| ucs2_bin | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ujis_bin | ujis | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| geostd8_general_ci | geostd8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| geostd8_bin | geostd8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| latin1_spanish_ci | latin1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp932_japanese_ci | cp932 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp932_bin | cp932 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| eucjpms_japanese_ci | eucjpms | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| eucjpms_bin | eucjpms | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| cp1250_polish_ci | cp1250 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_unicode_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_icelandic_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_latvian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_romanian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_slovenian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_polish_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_estonian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_spanish_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_swedish_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_turkish_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_czech_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_danish_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_lithuanian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_slovak_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_spanish2_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_roman_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_persian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_esperanto_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_hungarian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_sinhala_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_german2_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_croatian_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_unicode_520_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf16_vietnamese_ci | utf16 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_unicode_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_icelandic_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_latvian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_romanian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_slovenian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_polish_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_estonian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_spanish_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_swedish_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_turkish_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_czech_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_danish_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_lithuanian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_slovak_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_spanish2_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_roman_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_persian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_esperanto_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_hungarian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_sinhala_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_german2_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_croatian_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_unicode_520_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_vietnamese_ci | ucs2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ucs2_general_mysql500_ci | ucs2 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf32_unicode_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_icelandic_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_latvian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_romanian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_slovenian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_polish_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_estonian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_spanish_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_swedish_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_turkish_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_czech_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_danish_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_lithuanian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_slovak_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_spanish2_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_roman_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_persian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_esperanto_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_hungarian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_sinhala_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_german2_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_croatian_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_unicode_520_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf32_vietnamese_ci | utf32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_unicode_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_icelandic_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_latvian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_romanian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_slovenian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_polish_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_estonian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_spanish_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_swedish_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_turkish_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_czech_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_danish_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_lithuanian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_slovak_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_spanish2_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_roman_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_persian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_esperanto_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_hungarian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_sinhala_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_german2_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_croatian_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_unicode_520_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_vietnamese_ci | utf8 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8_general_mysql500_ci | utf8 | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf8mb4_unicode_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_icelandic_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_latvian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_romanian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_slovenian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_polish_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_estonian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_spanish_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_swedish_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_turkish_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_czech_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_danish_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_lithuanian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_slovak_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_spanish2_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_roman_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_persian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_esperanto_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_hungarian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_sinhala_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_german2_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_croatian_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_unicode_520_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| utf8mb4_vietnamese_ci | utf8mb4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| gb18030_chinese_ci | gb18030 | ⚠️ | ⚠️ | ❌ | ❌ | ❌ | ❌ | ❌ | +| gb18030_bin | gb18030 | ⚠️ | ⚠️ | ❌ | ❌ | ❌ | ❌ | ❌ | +| gb18030_unicode_520_ci | gb18030 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_de_pb_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_is_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_lv_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_ro_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_sl_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_pl_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_et_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_es_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_sv_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_tr_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_cs_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_da_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_lt_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_sk_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_es_trad_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_la_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_eo_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_hu_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_hr_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_vi_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_de_pb_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_is_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_lv_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_ro_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_sl_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_pl_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_et_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_es_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_sv_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_tr_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_cs_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_da_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_lt_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_sk_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_es_trad_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_la_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_eo_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_hu_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_hr_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_vi_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_ja_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_ja_0900_as_cs_ks | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_0900_as_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_ru_0900_ai_ci | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_ru_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_zh_0900_as_cs | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8mb4_0900_bin | utf8mb4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| utf8_croatian_ci | utf8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf8_myanmar_ci | utf8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf8_thai_520_w2 | utf8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ | +| utf8mb4_croatian_ci | utf8mb4 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf8mb4_myanmar_ci | utf8mb4 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf8mb4_thai_520_w2 | utf8mb4 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ | +| ucs2_croatian_ci | ucs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| ucs2_myanmar_ci | ucs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| ucs2_thai_520_w2 | ucs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ | +| utf16_croatian_ci | utf16 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf16_myanmar_ci | utf16 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf16_thai_520_w2 | utf16 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ | +| utf32_croatian_ci | utf32 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf32_myanmar_ci | utf32 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | +| utf32_thai_520_w2 | utf32 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ | +| big5_chinese_nopad_ci | big5 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| dec8_swedish_nopad_ci | dec8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp850_general_nopad_ci | cp850 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| hp8_english_nopad_ci | hp8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| koi8r_general_nopad_ci | koi8r | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin1_swedish_nopad_ci | latin1 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin2_general_nopad_ci | latin2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| swe7_swedish_nopad_ci | swe7 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ascii_general_nopad_ci | ascii | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ujis_japanese_nopad_ci | ujis | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| sjis_japanese_nopad_ci | sjis | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| hebrew_general_nopad_ci | hebrew | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| tis620_thai_nopad_ci | tis620 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| euckr_korean_nopad_ci | euckr | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| koi8u_general_nopad_ci | koi8u | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| gb2312_chinese_nopad_ci | gb2312 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| greek_general_nopad_ci | greek | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1250_general_nopad_ci | cp1250 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| gbk_chinese_nopad_ci | gbk | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin5_turkish_nopad_ci | latin5 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| armscii8_general_nopad_ci | armscii8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8_general_nopad_ci | utf8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ucs2_general_nopad_ci | ucs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp866_general_nopad_ci | cp866 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| keybcs2_general_nopad_ci | keybcs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| macce_general_nopad_ci | macce | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| macroman_general_nopad_ci | macroman | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp852_general_nopad_ci | cp852 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin7_general_nopad_ci | latin7 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| macce_nopad_bin | macce | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8mb4_general_nopad_ci | utf8mb4 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8mb4_nopad_bin | utf8mb4 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin1_nopad_bin | latin1 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1251_nopad_bin | cp1251 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1251_general_nopad_ci | cp1251 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| macroman_nopad_bin | macroman | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf16_general_nopad_ci | utf16 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf16_nopad_bin | utf16 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf16le_general_nopad_ci | utf16le | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1256_general_nopad_ci | cp1256 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1257_nopad_bin | cp1257 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1257_general_nopad_ci | cp1257 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf32_general_nopad_ci | utf32 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf32_nopad_bin | utf32 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf16le_nopad_bin | utf16le | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| armscii8_nopad_bin | armscii8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ascii_nopad_bin | ascii | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1250_nopad_bin | cp1250 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp1256_nopad_bin | cp1256 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp866_nopad_bin | cp866 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| dec8_nopad_bin | dec8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| greek_nopad_bin | greek | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| hebrew_nopad_bin | hebrew | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| hp8_nopad_bin | hp8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| keybcs2_nopad_bin | keybcs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| koi8r_nopad_bin | koi8r | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| koi8u_nopad_bin | koi8u | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin2_nopad_bin | latin2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin5_nopad_bin | latin5 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| latin7_nopad_bin | latin7 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp850_nopad_bin | cp850 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp852_nopad_bin | cp852 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| swe7_nopad_bin | swe7 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8_nopad_bin | utf8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| big5_nopad_bin | big5 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| euckr_nopad_bin | euckr | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| gb2312_nopad_bin | gb2312 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| gbk_nopad_bin | gbk | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| sjis_nopad_bin | sjis | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| tis620_nopad_bin | tis620 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ucs2_nopad_bin | ucs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ujis_nopad_bin | ujis | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| geostd8_general_nopad_ci | geostd8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| geostd8_nopad_bin | geostd8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp932_japanese_nopad_ci | cp932 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| cp932_nopad_bin | cp932 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| eucjpms_japanese_nopad_ci | eucjpms | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| eucjpms_nopad_bin | eucjpms | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf16_unicode_nopad_ci | utf16 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf16_unicode_520_nopad_ci | utf16 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ucs2_unicode_nopad_ci | ucs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| ucs2_unicode_520_nopad_ci | ucs2 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf32_unicode_nopad_ci | utf32 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf32_unicode_520_nopad_ci | utf32 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8_unicode_nopad_ci | utf8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8_unicode_520_nopad_ci | utf8 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8mb4_unicode_nopad_ci | utf8mb4 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | +| utf8mb4_unicode_520_nopad_ci | utf8mb4 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | + +### Configuring the default connection charset for a Vitess cluster + +**The default connection charset for a Vitess cluster is configured in your VTTablet instances** via the `--db_charset` flag. This flag modifies the behavior of the _connections_ that the tablet creates, not the underlying MySQL instance: it defines the charset that VTTablet uses when opening connections to MySQL. +If the `--db_charset` flag is left empty, VTTablet will default to an `utf8mb4` charset based on the underlying MySQL version. For instance, MySQL 5.x will default to `utf8mb4_general_ci`, while MySQL 8.x defaults to `utf8mb4_0900_ai_ci`. Because the handshake packet of MySQL leaves only 1 byte to reference the charset ID, only charset IDs <= 255 are supported. + +The `@character_set_client` of a VTTablet is automatically propagated to all the VTGates that connect to it, and hence to all the MySQL clients connected to the VTGates. It is a configuration error to deploy several VTTablets in the same Vitess cluster with different connection charset: it will cause warning messages in the VTGates and lead to inconsistent behaviors. + +**The `@character_set_client` of a Vitess cluster is constant**: it cannot be changed at runtime via SQL (e.g. by issuing a `SET character_set_client = utf8` statement). VTGates will reject such queries. + +Do note that, as the MySQL documentation explains, the `@character_set_client` setting only applies when performing character comparisons in SQL queries that don't have explicit collation information. For instance, a query such as `SELECT 'foo' = 'FOO'` will use the default `@character_set_client` for the cluster when picking the charset and collation for the two string literals, because these literals contain no explicit charset or collation information. A query such as `SELECT c FROM t WHERE c = 'foo'` will **not** use the `@character_set_client`; it will use the charset and collation that was defined for column `c` when creating table `t`. + +Vitess has extensive support for creating collation-aware tables and columns in your SQL database, using any charset, and performing collation-aware operations in SQL queries. Any of the supported collations and charsets in Vitess can be used when declaring a table or a row in your database -- it does not need to match the specific value of `@character_set_client`. Generally speaking, setting `@character_set_client` to a charset not based on `utf8mb4` is a mistake. We strongly encourage you to leave the `--db_charset` flag to its default value. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/create-cell.md b/content/en/docs/19.0/user-guides/configuration-basic/create-cell.md new file mode 100644 index 000000000..4e4f92711 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/create-cell.md @@ -0,0 +1,56 @@ +--- +title: Creating a cell +weight: 6 +--- + +A Vitess [cell](../../../concepts/cell) is a logical grouping of servers that typically maps to an availability zone, region, or data center. The purpose of a cell is to provide isolation. The loss of one cell should not disrupt other cells. To fulfil this, Vitess allows you to configure separate cell-specific topo servers. There is no need to distribute the servers of a cell-specific toposerver to other cells. However, it is recommended that you bring up more than one instance in order to survive individual server failures. + +Even if you do not want a multi-cell deployment, you still need to create at least one cell before bringing up the rest of the Vitess servers. If you do not plan to deploy multiple cells, you can reuse the global toposerver as the cell-specific one also. + +You can use the `vtctldclient` alias to create one: + +```sh +vtctldclient AddCellInfo \ + --root /vitess/cell1 \ + --server-address \ + cell1 +``` + +Note that the cell topo has its own root path. If reusing the same toposerver, you must ensure that they don’t overlap. + +The cell information is saved in the global toposerver. Vitess takes care of deploying the necessary information from the global topo to the cell-specific topos. Vitess binaries fetch the cell information from the global topo before switching to use the cell topo. + +{{< info >}} +You will only need to specify the topo global root for launching the Vitess servers. The cell-specific information including its root path will be automatically loaded from the cell info. +{{< /info >}} + +## Mapping cells to zones and regions + +Most public clouds offer a hierarchy of failure boundaries. Regions are data centers that are far apart. Depending on the distance, the latency between two regions can be in the 10s to 100s of milliseconds. Zones are partitions within a region where the machines are in different buildings. Latency between zones is typically in the range of sub-millisecond to 1-2ms. + +There is also a cost to transferring data between zones and regions, and these costs can come into play when making decisions about how to layout the topology. + +The general recommendation for Vitess is to map each cell to a zone. The main advantage of this approach is that it minimizes cross-zone data transfers to the extent possible, thereby minimizing cost. + +If an application must be deployed across regions, then you can create more cells in the newer region, one for each zone. + +Within a region, you could use a single topo cluster to serve all the cells, as long as their root paths are distinct, or you could use one topo cluster per cell. The decision depends on the kind of failure tolerance you want to build into the system. + +For example, let us say that you plan to deploy in three zones and decided to use a shared topo. In this case, losing two zones will result in a full outage because the topo server in the third zone would become unavailable due to loss of quorum. On the other hand, deploying a separate topo cluster for each cell would allow the third zone to survive the loss of the other two zones. + +If you intend to use more than one region for the sake of survivability, then it is recommended that you use at least three regions. This will allow you to deploy a balanced quorum of servers for the global topo. + +If you have deployed in multiple regions and would like the flexibility of queries that go cross-cell within a region, you can create [cell aliases](../../../reference/programs/vtctl/cell-aliases). These aliases will indicate to the vtgates that they can send requests to the vttablets of a different cell if a no local vttablet is available. + +## Checklist + +* Ensure that vtctlds come up successfully. If there is a failure, check the log files for any errors. +* Ensure that you can query the http port of vtctld: `curl http://localhost:15000/cells/` +* If you configured a separate cell-specific topo, ensure that you can connect to it using the parameters in the cell information. +* Ensure that the cell-specific topos are reachable from other cells. + +Open the VTAdmin application in your browser. Go to Topology > View Topology +Browsing to the cell information should look like this screenshot: + +![cell-in-topo](../img/cell-in-topo.png) + diff --git a/content/en/docs/19.0/user-guides/configuration-basic/delete-keyspace.md b/content/en/docs/19.0/user-guides/configuration-basic/delete-keyspace.md new file mode 100644 index 000000000..a83c2e296 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/delete-keyspace.md @@ -0,0 +1,31 @@ +--- +title: Delete a Keyspace +weight: 14 +--- + +Although adding a keyspace is implicit, deleting one is not. In order to delete a keyspace, you must first bring down all tablets on that keyspace. + +Following this, you should delete all shards of a keyspace. In the current example, `commerce` has only one shard (`0`). You can use the following command to delete it: + +```text +vtctldclient DeleteShards --recursive commerce/0 +``` + +The `recursive` flag is required to ensure that the shard is deleted from all cells. If there are tablets still running against the shard, the command will fail. + +You can add an `--even_if_serving` flag to ignore running tablets, but it is not recommended. Otherwise, this would cause existing vttablets to get confused about their tablet records being deleted. + +If a keyspace has more than one shard, you may pass multiple shard names to `DeleteShards`. +They will be deleted sequentially; if one deletion fails, the operation stops there. + +{{< warning>}} +Deleting a shard also deletes the metadata for all the backups, but it does not delete the backups themselves. This is something you have to do manually. +{{< /warning >}} + +Once all shards are deleted, you can delete the keyspace with: + +```text +vtctldclient DeleteKeyspace commerce +``` + +`DeleteKeyspace` also supports a `--recursive` flag that loops through all shards and deletes them recursively, but also ignores any tablets that are running. Note that restarting a vttablet for the deleted keyspace will cause the keyspace to be recreated. This is yet another reason for ensuring that all vttablets are shutdown upfront. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/durability_policy.md b/content/en/docs/19.0/user-guides/configuration-basic/durability_policy.md new file mode 100644 index 000000000..d87a2f68b --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/durability_policy.md @@ -0,0 +1,29 @@ +--- +title: Durability Policy +weight: 10 +--- + +Vitess now supports a configurable interface for durability policies. Users can now define, in the interface, which tablets are eligible to be promoted to a PRIMARY instance. They can also specify the number of semi-sync ACKs it requires and the tablets which are eligible to send these ACKs. + +The interface definition looks like: +```go +// Durabler is the interface which is used to get the promotion rules for candidates and the semi sync setup +type Durabler interface { + promotionRule(*topodatapb.Tablet) promotionrule.CandidatePromotionRule + semiSyncAckers(*topodatapb.Tablet) int + isReplicaSemiSync(primary, replica *topodatapb.Tablet) bool +} +``` + +There are 3 implementations supported in this release: + - ***semi_sync*** - This durability policy sets the number of required semi-sync ACKers to 1. It only allows Primary and Replica type servers to acknowledge semi sync. It returns NeutralPromoteRule for replica tablet types, MustNotPromoteRule for everything else. + - ***semi_sync_with_rdonly_ack*** - This durability policy sets the number of required semi-sync ACKers to 1. It allows Primary, Replica and Rdonly type servers to acknowledge semi sync. It returns NeutralPromoteRule for replica tablet types, MustNotPromoteRule for everything else. + - ***none** (default)* - This durability policy does not set any semi-sync configurations. It returns NeutralPromoteRule for Primary and Replica tablet types, MustNotPromoteRule for everything else + - ***cross_cell*** - This durability policy sets the number of required semi-sync ACKers to 1. It only allows Primary and Replica type servers from a different cell than the current primary to acknowledge semi sync. It returns NeutralPromoteRule for replica tablet types, MustNotPromoteRule for everything else. + - ***cross_cell_with_rdonly_ack*** - This durability policy sets the number of required semi-sync ACKers to 1. It only allows Primary, Replica and Rdonly type servers from a different cell than the current primary to acknowledge semi sync. It returns NeutralPromoteRule for replica tablet types, MustNotPromoteRule for everything else. + + +[EmergencyReparentShard](../../configuration-advanced/reparenting/#emergencyreparentshard-emergency-reparenting) and [PlannedReparentShard](../../configuration-advanced/reparenting/#plannedreparentshard-planned-reparenting) will use the durability rules while choosing the correct candidate for promotion. + +This configuration must be stored in the topo server in the keyspace record using the command [CreateKeyspace](../../../reference/programs/vtctldclient/vtctldclient_createkeyspace/) or [SetKeyspaceDurabilityPolicy](../../../reference/programs/vtctldclient/vtctldclient_setkeyspacedurabilitypolicy/). + diff --git a/content/en/docs/19.0/user-guides/configuration-basic/exporting-data.md b/content/en/docs/19.0/user-guides/configuration-basic/exporting-data.md new file mode 100644 index 000000000..17c9e7809 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/exporting-data.md @@ -0,0 +1,72 @@ +--- +title: Exporting data from Vitess +weight: 18 +aliases: ['/docs/user-guides/exporting-data/'] +--- + +Since [VTGate](../../../concepts/vtgate/) supports the MySQL protocol, in many +cases it is possible to use existing client utilities when connecting to +Vitess. This includes using logical dump tools such as `mysqldump`, in +certain cases. + +This guide provides instructions on the required options when using these tools +against a VTGate server for the purposes of exporting data from Vitess. It is +recommended to follow the [Backup and Restore](../../operating-vitess/backup-and-restore/) guide +for regular backups, since this method is performed directly on the tablet +servers and is more efficient and safer for databases of any significant size. +The dump methods that follow are typically not suitable for production backups, +because Vitess does not implement all the locking constructs across a sharded +database that are necessary to do a consistent logical backup while writing +to the database. As a result, you will only be guaranteed to get a 100% +consistent dump using these tools if you are sure that you are not writing +to the database while running the dump. + +### mysqldump + +The default invocation of `mysqldump` attempts to execute statements which are [not supported by Vitess](../../../reference/compatibility/mysql-compatibility/), such as attempting to lock tables and dump GTID coordinates. The following options are required when using the `mysqldump` binary from MySQL 5.7 to export data from the `commerce` keyspace: + +* `--lock-tables=off`: VTGate currently prohibits the syntax `LOCK TABLES` and `UNLOCK TABLES`. +* `--set-gtid-purged=OFF`: `mysqldump` attemps to dump GTID coordinates of a server, but in the case of VTGate this does not make sense since it could be routing to multiple servers. +* `--no-tablespaces`: This option disables dumping InnoDB tables by tablespace. This functionality is not yet supported by Vitess. +* `....`: Additional mysqldump options like: `-u `, `-p `, `-h `. + +For example to export the `commerce` keyspace using the `mysqldump` binary from MySQL 5.7: + +```sh +$ mysqldump --set-gtid-purged=OFF --no-tablespaces .... commerce > commerce.sql +``` +{{< info >}} +Vitess' support for LOCK and UNLOCK statements is currently syntax-only. As a result, Vitess will simply ignore LOCK and UNLOCK statements without taking any underlying action. It is therefore *unsafe* to perform a locking mysqldump against a database that is actively being written to, and you should pause writes completely while performing the dump; or be willing to deal with any data inconsistencies that result. +{{< /info >}} + +**NOTE:** You will be limited by the Vitess row limits in the size of the +tables that you can dump using this method. The default Vitess row limit is +determined by the vttablet option `-queryserver-config-max-result-size` +and defaults to 10000 rows. So for an unsharded database, you will not be +able to dump tables with more than 10000 rows, or N x 10000 rows if the table +is fully sharded across N shards. Note that you should not blindly raise your +row limits just because of this, it is an important Vitess operability +and reliability feature. If you have large tables to dump, look into using +[go-mydumper](#go-mydumper) instead. + +To restore dump files created by `mysqldump`, replay it against a Vitess +server or other MySQL server using the `mysql` command line client. + +### go-mydumper + +Alternatively, you can use a slight modification of the `go-mydumper` tool +to export logical dumps of a Vitess keyspace. `go-mydumper` has the +advantage of being multi-threaded, and so can run faster on a database +that has many tables. For a database with just one or a handful of large +tables, `go-mydumper` may not be that much faster than `mysqldump`. + +For information on the Vitess-compatible fork of `go-mydumper`, see +https://github.com/aquarapid/go-mydumper . Examples and instructions +are available in the [README.md](https://github.com/aquarapid/go-mydumper/blob/jacques_vitess/README.md) +in that repo. You will need to be able to compile golang binaries +to use this tool. + +`go-mydumper` creates multiple files for each backup. To restore a +backup, you can use the `mysql` commandline client, but using the +`myloader` tool as described in the `go-mydumper` repo above is easier +and can be faster, since the loader is also multithreaded. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/global-topo.md b/content/en/docs/19.0/user-guides/configuration-basic/global-topo.md new file mode 100644 index 000000000..75b6ea689 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/global-topo.md @@ -0,0 +1,52 @@ +--- +title: Global TopoServer +weight: 4 +aliases: ['/docs/user-guide/topology-service/'] +--- + +The first component to bring up is the Global TopoServer. As mentioned before, this can be a zookeeper or etcd cluster. The servers will likely have to be distributed across data centers for resilience. Please refer to the corresponding documentation for instructions on how to configure and launch these servers. + +{{< info >}} +Vitess previously supported Consul as a TopoServer. However, it is now deprecated because Consul does not natively support the ability to connect to multiple servers from a single program. This is a prerequisite for multi-region deployments. +{{< /info >}} + +Vitess will store global metadata like keyspaces, shards and cells in the topserver. + +## Choosing a TopoRoot + +Vitess allows you to share the same global toposerver for multiple clusters. For example, you may want to run separate testing, staging and production clusters. + +To support this separation, we allow you to assign a root directory in the Topo for each cluster. This directory is known as the `topo_global_root` and will need to be provided as a command line flag to every Vitess component. + +{{< info >}} +In the case of ZooKeeper, you will also need to create this directory on the server. For etcd, the path will be automatically created on first write. +{{< /info >}} + +The following command line options are required for every Vitess component: + +```text +--topo_implementation=etcd2 --topo_global_server_address= --topo_global_root=/vitess/global +``` + +To avoid repetition we will use `` in our examples to signify the above flags. + +Note that the topo implementation for etcd is `etcd2`. This is because Vitess uses the v2 API of etcd. + +{{< info >}} +To be safe, you may want to bring up etcd with `--enable-v2=true`, even though it is the default value. Also, you will need to set the `ETCDCTL_API=2` environment variable before bringing up etcd. +{{< /info >}} + +## Moving to a different TopoServer + +It is generally not recommended that you migrate from one type of toposerver to another. However, if absolutely necessary, you can use the [topo2topo](../../../reference/features/topology-service/#migration-between-implementations) command line tool to perform this migration. + +## Backups + +It is important to periodically backup the data in the TopoServer. Although most of the information in the TopoServer can be manually reconstructed, it is still a painful task. This can be avoided if a recent backup was readily available. + +## Checklist + +* Ensure toposerver is up, and that you can set and get values using their provided client tools. +* Ensure you have the mechanism to include the correct topo flags for all the components: `--topo_implementation`, `--topo_global_server_address` and `--topo_global_root`. +* If using zookeeper, ensure the global root path is created. It may be beneficial to do the same for etcd also. +* Ensure that the servers are reachable from other parts of the system where Vitess components will be launched. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/img/cell-in-topo.png b/content/en/docs/19.0/user-guides/configuration-basic/img/cell-in-topo.png new file mode 100644 index 000000000..3d106ec19 Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-basic/img/cell-in-topo.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-basic/img/healthy-tablet.png b/content/en/docs/19.0/user-guides/configuration-basic/img/healthy-tablet.png new file mode 100644 index 000000000..857923723 Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-basic/img/healthy-tablet.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-basic/img/unhealthy-tablet.png b/content/en/docs/19.0/user-guides/configuration-basic/img/unhealthy-tablet.png new file mode 100644 index 000000000..55f72aedb Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-basic/img/unhealthy-tablet.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-basic/img/vtadmin-reparenting.png b/content/en/docs/19.0/user-guides/configuration-basic/img/vtadmin-reparenting.png new file mode 100644 index 000000000..abdd6f5df Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-basic/img/vtadmin-reparenting.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-basic/img/vtadmin-tablet-list.png b/content/en/docs/19.0/user-guides/configuration-basic/img/vtadmin-tablet-list.png new file mode 100644 index 000000000..828d033f5 Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-basic/img/vtadmin-tablet-list.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-basic/img/vtgate-healthy-tablets.png b/content/en/docs/19.0/user-guides/configuration-basic/img/vtgate-healthy-tablets.png new file mode 100644 index 000000000..b0ac5e780 Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-basic/img/vtgate-healthy-tablets.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-basic/img/vtgate-partially-healthy-tablets.png b/content/en/docs/19.0/user-guides/configuration-basic/img/vtgate-partially-healthy-tablets.png new file mode 100644 index 000000000..ba2a6ab79 Binary files /dev/null and b/content/en/docs/19.0/user-guides/configuration-basic/img/vtgate-partially-healthy-tablets.png differ diff --git a/content/en/docs/19.0/user-guides/configuration-basic/initialize-shard-primary.md b/content/en/docs/19.0/user-guides/configuration-basic/initialize-shard-primary.md new file mode 100644 index 000000000..717de8b08 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/initialize-shard-primary.md @@ -0,0 +1,34 @@ +--- +title: Initialize Shard Primary +weight: 9 +--- + +A new primary is elected automatically by VTOrc and no user action is required. + +The InitShardPrimary command can be used to do the same operation manually. However, it is a destructive command and should only be used by advanced users. This command copies over the `executed_gtid_set` from the primary to the replica which can break replication if the user isn't careful. + +The command for `InitShardPrimary` is as follows: + +```text +vtctldclient \ + InitShardPrimary \ + --force \ + commerce/0 \ + cell1-100 +``` + +Until this step is complete, you may see errors like this in the vttablet logs: `Cannot start query service: Unknown database 'vt_xxx'`. This is because the database will be created only after a primary is elected. + +If you have semi-sync enabled and did not set up at least two replicas, InitShardPrimary could hang indefinitely. Even if it succeeds, future operations that perform failovers could cause this shard to go into a deadlocked state. + +After this step, visiting the `/debug/status` page on the vttablets should show all the tablets as healthy: + +![healthy-tablet](../img/healthy-tablet.png) + +{{< warning >}} +`InitShardPrimary` is a destructive command that resets all servers by deleting their binlog metadata. It should only be used for initializing a brand new cluster. +{{< /warning >}} + +{{< info >}} +`InitShardPrimary` is deprecated. This action is performed automatically by VTOrc. If manual action is needed, it is recommended to use `PlannedReparentShard`. +{{< /info >}} diff --git a/content/en/docs/19.0/user-guides/configuration-basic/keyspaces-shards.md b/content/en/docs/19.0/user-guides/configuration-basic/keyspaces-shards.md new file mode 100644 index 000000000..09cc4a162 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/keyspaces-shards.md @@ -0,0 +1,14 @@ +--- +title: Keyspaces and Shards +weight: 7 +--- + +You can create keyspaces and shards using [vtctldclient](../../../reference/programs/vtctldclient) commands. However, they are not necessary because these are implicitly created as you bring up the vttablets. + +The canonical information for keyspaces and shards is initially created in the global topo. This information is then deployed to the cell-specific topos through rebuild commands like `RebuildKeyspaceGraph` and `RebuildVSchemaGraph`. These commands are implicitly issued on your behalf whenever applicable. But there are situations where you will have to issue them manually. For example, if you create a new cell, you will have to issue these commands to copy the data into the new cell. + +There are use cases where you may want to experimentally deploy changes to only some cells. Separating information from the global topo and local cells makes those experiments possible without affecting the entire deployment. + +Tools like [vtgate](../../../reference/programs/vtgate) and [vttablet](../../../reference/programs/vttablet) consume information from the local copy of the topo. + +An unsharded keyspace typically has a single shard named `0` or` -`. A sharded keyspace has shards named after the keyranges assigned to it, like `-80` and `80-`. Please refer to the section on [shard naming](../../../concepts/shard/#shard-naming) for more info on how shards are named. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/monitoring.md b/content/en/docs/19.0/user-guides/configuration-basic/monitoring.md new file mode 100644 index 000000000..2bbbc111c --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/monitoring.md @@ -0,0 +1,403 @@ +--- +title: Monitoring +weight: 16 +aliases: ['/docs/launching/server-configuration/', '/docs/user-guides/server-configuration/', '/docs/user-guides/configuring-components/'] +--- + +This section describes how to monitor Vitess components. Additionally, we recommend that you also add the necessary monitoring and alerting for the TopoServers as well as the MySQL instances running with each vttablet. + +## Tools + +Vitess provides integrations with a variety of popular monitoring tools: Prometheus, InfluxDB and Datadog. The core infrastructure uses go's `expvar` package to export real-time variables visible as a JSON object served by the `/debug/vars` URL. The exported variables are CamelCase names. These names are algorithmically converted to the appropriate naming standards for each monitoring tool. For example, Prometheus uses a [snake case conversion algorithm](https://github.com/vitessio/vitess/blob/e259a08f017d9f1b5984fcaac5c54e26d1c7c31d/go/stats/prometheusbackend/prometheusbackend.go#L95-L116). In this case, the Prometheus exporter would convert the `Queries.Histograms.Select.500000` variable to `vttablet_queries_bucket{plan_type="Select",le="0.0005"}`. + +In the sections below, we will be describing the variables as seen in the `/debug/vars` page. + +The two critical Vitess processes to monitor are vttablet and vtgate. Additionally, we recommend that you setup monitoring for the underlying MySQL instances as commonly recommended in the MySQL community. + +Beyond what the tools export, it is important to also monitor system resource usage: CPU, memory, network and disk usage. + +There is a [popular mixin](https://github.com/vitessio/vitess/tree/main/vitess-mixin) contributed by [Slack](https://slack.com) that is based on how they monitor Vitess internally. It can be used as a starting point if you intend to use Prometheus and Grafana. + +Beyond the monitoring variables, the Vitess processes export additional information about their status on other URL paths. Some of those pages are for human consumption, and others are machine-readable meant for building automation. + +## VTTablet + +### /debug/status + +This page has a variety of human-readable information about the current vttablet and contains links to all the other URLs. You can look at this page to get a general overview of what is going on. + +### /debug/vars + +The following sections describe the various sub-objects of the JSON object exported by `/debug/vars`. These variables can be found at the top level of the JSON object: + +#### Queries + +Vitess has a structured way of exporting certain performance stats. The most common one is the Histogram structure, which is used by Queries: + +``` json + "Queries": { + "Histograms": { + "Select": { + "1000000": 1138196, + "10000000": 1138313, + "100000000": 1138342, + "1000000000": 1138342, + "10000000000": 1138342, + "500000": 1133195, + "5000000": 1138277, + "50000000": 1138342, + "500000000": 1138342, + "5000000000": 1138342, + "Count": 1138342, + "Time": 387710449887, + "inf": 1138342 + } + }, + "TotalCount": 1138342, + "TotalTime": 387710449887 + }, +``` + +The histograms are broken out into query categories. In the above case, `Select` is the only category, which measures all SELECT statements. An entry like `"500000": 1133195` means that `1133195` queries took under `500000` nanoseconds to execute. + +Here is the full list of categories [expanded from the source](https://github.com/vitessio/vitess/blob/e259a08f017d9f1b5984fcaac5c54e26d1c7c31d/go/vt/vttablet/tabletserver/planbuilder/plan.go#L79-L102): + +``` +Select +SelectLock +Nextval +SelectImpossible +Insert +InsertMessage +Update +UpdateLimit +Delete +DeleteLimit +DDL +Set +OtherRead +OtherAdmin +SelectStream +MessageStream +Savepoint +Release +RollbackSavepoint +ShowTables +Load +Flush +LockTables +UnlockTables +``` + +The numbers are cumulative. For example, if you wish to count how many queries took between `500000ns` and `1000000ns`, the answer would be `1138196-1133195`, which is `1`. + +Later below, we will be covering variables that break out these queries into further sub-categories like per-table, etc. However, we do not generate histograms for them because the number of values generated would be too big. + +The thresholds are hard-coded. However, if you are integrating with an extermal tool like Prometheus, it will have its own thresholds. + +The counters increment for the lifetime of the vttablet, and all values are updated in real-time. + +`Queries.Histograms.Select.Count` is the total count in the `Select` category. + +`Queries.Histograms.Select.Time` is the total time in the `Select` category. + +`Queries.TotalCount` is the total count across all categories. + +`Queries.TotalTime` is the total time across all categories. + +There are other Histogram variables described below, and they will always have the same structure. + +Use this variable to track: + +* QPS +* Latency +* Per-category QPS. For replicas, the only category will be `Select`, but there will be more for primary tablets. +* Per-category latency +* Per-category tail latency +* Per-category cost: This value is calculated as QPS\*Latency. If the latency of a high QPS query goes up, it is likely causing more harm than the latency increase of an occasional query. + +#### Results + +```json + "Results": { + "0": 0, + "1": 0, + "10": 1138326, + "100": 1138326, + "1000": 1138342, + "10000": 1138342, + "5": 1138326, + "50": 1138326, + "500": 1138342, + "5000": 1138342, + "Count": 1138342, + "Total": 1140438, + "inf": 1138342 + } +``` + +Results is a simple histogram with no timing info. It gives you a histogram view of the number of rows returned per query. This does not include rows affected from write queries. + +`Count` is expected to be the same as the `TotalCount` of the `Queries` histogram. + +`Total` is the total number of rows returned so far. + +#### Mysql + +Mysql is a histogram variable like Queries, except that it reports MySQL execution times. The categories are "Exec" and “ExecStream”. + +The vttablet queries exec time is roughly equal to the sum of the MySQL exec time, `ConnPoolWaitTime` and `Waits.Consolidations`. + +#### Transactions + +`Transactions` is a histogram variable that tracks transactions. The categories are "Completed" and “Aborted”. Since these are histograms, they include count as well as timings. + +#### Waits + +Waits is a histogram variable that tracks various waits in the system. Right now, the only category is "Consolidations". A consolidation happens when one query waits for the results of an identical query already executing, thereby saving the database from performing duplicate work. + +This variable used to report connection pool waits, but a refactor moved those variables out into the pool related vars. + +#### Errors + +``` json + "Errors": { + "OK": 0, + "CANCELED": 0, + "UNKNOWN": 0, + "INVALID_ARGUMENT": 1, + "DEADLINE_EXCEEDED": 0, + "NOT_FOUND": 0, + "ALREADY_EXISTS": 0, + "PERMISSION_DENIED": 0, + "RESOURCE_EXHAUSTED": 0, + "FAILED_PRECONDITION": 0, + "ABORTED": 0, + "OUT_OF_RANGE": 0, + "UNIMPLEMENTED": 0, + "INTERNAL": 0, + "UNAVAILABLE": 0, + "DATA_LOSS": 0, + "UNAUTHENTICATED": 0, + "CLUSTER_EVENT": 0, + "READ_ONLY": 0, + }, +``` + +Errors are reported under different categories. It’s beneficial to track each category separately as it will be more helpful for troubleshooting. Right now, there are eighteen categories. The category list may vary as Vitess evolves. + +Errors/Query is a useful stat to track. + +#### InternalErrors + +``` json + "InternalErrors": { + "Task": 0, + "StrayTransactions": 0, + "Panic": 0, + "HungQuery": 0, + "Schema": 0, + "TwopcCommit": 0, + "TwopcResurrection": 0, + "WatchdogFail": 0, + "Messages": 0, + }, +``` + +An internal error is an unexpected situation in code that may possibly point to a bug. Such errors may not cause outages, but even a single error needs to be escalated for root cause analysis. + +#### Kills + +``` json + "Kills": { + "Queries": 2, + "Transactions": 0, + "ReservedConnection": 0 + }, +``` + +Kills reports the queries, transactions and reserved connections killed by vttablet due to timeout. It is a very important variable to look at during incidents. + +#### TransactionPool\* and FoundRowsPool\* + +There are a few variables with the above prefixes that report the status of the two transaction pools: + +``` json + "TransactionPoolActive": 0, + "TransactionPoolAvailable": 20, + "TransactionPoolCapacity": 20, + "TransactionPoolDiffSetting": 0, + "TransactionPoolExhausted": 0, + "TransactionPoolGet": 0, + "TransactionPoolGetConnTime": {"TotalCount":0,"TotalTime":0,"Histograms":{}}, + "TransactionPoolGetSetting": 0, + "TransactionPoolIdleClosed": 0, + "TransactionPoolIdleTimeout": 1800000000000, + "TransactionPoolInUse": 0, + "TransactionPoolMaxCap": 20, + "TransactionPoolMaxLifetimeClosed": 0, + "TransactionPoolResetSetting": 0, + "TransactionPoolWaitCount": 0, + "TransactionPoolWaitTime": 0, + "TransactionPoolWaiterQueueFull": 0, + "FoundRowsPoolActive": 0, + "FoundRowsPoolAvailable": 20, + "FoundRowsPoolCapacity": 20, + "FoundRowsPoolDiffSetting": 0, + "FoundRowsPoolExhausted": 0, + "FoundRowsPoolGet": 0, + "FoundRowsPoolGetConnTime": {"TotalCount":0,"TotalTime":0,"Histograms":{}}, + "FoundRowsPoolGetSetting": 0, + "FoundRowsPoolIdleClosed": 0, + "FoundRowsPoolIdleTimeout": 1800000000000, + "FoundRowsPoolInUse": 0, + "FoundRowsPoolMaxCap": 20, + "FoundRowsPoolMaxLifetimeClosed": 0, + "FoundRowsPoolResetSetting": 0, + "FoundRowsPoolWaitCount": 0, + "FoundRowsPoolWaitTime": 0, + "FoundRowsPoolWaiterQueueFull": 0, +``` + +The choice of which pool gets used depends on whether the application connected with the `CLIENT_FOUND_ROWS` flag or not. + +* `WaitCount` will give you how often the transaction pool gets full, which causes new transactions to wait. +* `WaitTime`/`WaitCount` will tell you the average wait time. +* `Available` is a gauge that tells you the number of available connections in the pool in real-time. `Capacity-Available` is the number of connections in use. Note that this number could be misleading if the traffic is spiky. + +#### Other Pool variables + +Just like `TransactionPool`, there are variables for other pools: + +* `ConnPool`: This is the pool used for read traffic. +* `StreamConnPool`: This is the pool used for streaming queries. + +There are other internal pools used by vttablet that are not very consequential. + +#### `TableACLAllowed`, `TableACLDenied`, `TableACLPseudoDenied` + +The above three variables are table acl stats. They are broken out by table, plan and user. + +#### `QueryPlanCacheSize` + +If the application does not make good use of bind variables, this value would reach the QueryCacheCapacity. If so, inspecting the current query cache will give you a clue about where the misuse is happening. + +#### `QueryCounts`, `QueryErrorCounts`, `QueryRowCounts`, `QueryTimesNs` + +These variables are another multi-dimensional view of Queries. They have a lot more data than Queries because they’re broken out into tables as well as plan. This is a priceless source of information when it comes to troubleshooting. If an outage is related to rogue queries, the graphs plotted from these vars will immediately show the table on which such queries are run. After that, a quick look at the detailed query stats will most likely identify the culprit. + +#### `UserTableQueryCount`, `UserTableQueryTimesNs`, `UserTransactionCount`, `UserTransactionTimesNs` + +These variables are yet another view of Queries, but broken out by user, table and plan. If you have well-compartmentalized app users, this is another priceless way of identifying a rogue "user app" that could be misbehaving. + +#### /debug/health + +This URL prints out a simple "ok" or “not ok” string that can be used to check if the server is healthy. The health check makes sure mysqld connections work, and replication is configured (though not necessarily running) if not on primary. + +#### /debug/status\_details + +This URL prints out a JSON object that lists the state of all the variables that contribute to the current healthy or unhealthy state of a vttablet. If healthy, you should see something like this: + +```json +[ + { + "Key": "Current State", + "Class": "healthy", + "Value": "PRIMARY: Serving, Jan 13, 2021 at 20:52:13 (PST)" + } +] +``` + +#### /queryz, /debug/query\_stats, /debug/tablet\_plans, /livequeryz + +* /queryz is a human-readable version of /debug/query\_stats. If a graph shows a table as a possible source of problems, this is the next place to look to see if a specific query is the root cause. This is list is sorted in descending order of query latency. If the value is greater than 100 milliseconds, it's color-coded red. If it is greater than 10 milliseconds, it is color coded yellow. Otherwise, it is color coded gray. +* /debug/query\_stats is a JSON view of the per-query stats. This information is pulled in real-time from the query cache. The per-table stats in /debug/vars are a roll-up of this information. +* /debug/tablet\_plans is a more static view of the query cache. It just shows how vttablet will process or rewrite the input query. +* /livequeryz lists the currently running queries. You have the option to kill any of them from this page. + +#### /querylogz, /debug/querylog, /txlogz, /debug/txlog + +* /debug/querylog is a continuous stream of verbose execution info as each query is executed. This URL can generate a lot of data because it streams every query processed by vttablet. The details are as per this function: https://github.com/vitessio/vitess/blob/main/go/vt/vttablet/tabletserver/tabletenv/logstats.go#L179 +* /querylogz is a limited human readable version of /debug/querylog. It prints the next 300 queries by default. The limit can be specified with a limit=N parameter on the URL. +* /txlogz is like /querylogz, but for transactions. +* /debug/txlog is the JSON counterpart to /txlogz. + +#### /debug/consolidations + +This URL has an MRU list of consolidations. This is a way of identifying if multiple clients are spamming the same query to a server. + +#### /schemaz, /debug/schema + +* /schemaz shows the schema info loaded by vttablet. +* /debug/schema is the JSON version of /schemaz. + +#### /debug/query\_rules + +This URL displays the currently active query blacklist rules. + +### Alerting + +Alerting is built on top of the variables you monitor. Before setting up alerts, you should get some baseline stats and variance, and then you can build meaningful alerting rules. You can use the following list as a guideline to build your own: + +* Query latency among all vttablets +* Per keyspace latency +* Errors/query +* Memory usage +* Unhealthy for too long +* Too many vttablets down +* Health has been flapping +* Transaction pool full error rate +* Any internal error +* Traffic out of balance among replicas +* QPS/core too high +* High replication lag +* Errant transactions +* Primary is in read-only mode + +## VTGate + +### /debug/status + +This is the landing page for a vtgate, which gives you the status of how a particular server is doing. Of particular interest there is the list of tablets this vtgate process is connected to, as this is the list of tablets that can potentially serve queries. + +### /debug/vars + +#### VTGateApi + +This is the main histogram variable to track for vtgates. It gives you a break up of all queries by command, keyspace, and type. + +#### HealthcheckConnections + +It shows the number of tablet connections for query/healthcheck per keyspace, shard, and tablet type. + +#### TopologyWatcherErrors and TopologyWatcherOperations + +These two variables track events related to how vtgate watches the topology. It is particularly important to monitor the error count. This can act as an early warning sign if a vtgate is not able to refresh the list of tablets from the topo. + +#### VindexUnknownParameters + +Gauges the number of unknown Vindex params in the latest VSchema obtained from the topology. + +### /debug/health + +This URL prints out a simple "ok" or “not ok” string that can be used to check if the server is healthy. + +### /debug/querylogz, /debug/querylog, /debug/queryz, /debug/query\_plans + +These URLs are similar to the ones exported by vttablet, but apply to the current vtgate instance. + +### /debug/vschema + +This URL shows the vschema as loaded by vtgate. + +### Alerting + +For vtgate, here’s a list of possible variables to alert on: + +* Error rate +* Error/query rate +* Error/query/tablet-type rate +* vtgate serving graph is stale by x minutes (topology service is down) +* QPS/core +* Latency + diff --git a/content/en/docs/19.0/user-guides/configuration-basic/planning.md b/content/en/docs/19.0/user-guides/configuration-basic/planning.md new file mode 100644 index 000000000..8850080e7 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/planning.md @@ -0,0 +1,69 @@ +--- +title: Planning +weight: 3 +aliases: ['/docs/user-guides/configuration-basic/configuring-components/'] +--- + +This guide explains how to bring up and manage a Vitess cluster. We cover every individual component of Vitess and how they interact with each other. If you are deploying on Kubernetes, a lot of the wire-up is automatically handled by the operator. However, it is still important to know how the components work in order to be able to troubleshoot problems if they occur in production. + +We assume that you are familiar with the setup of your production environment. If operating in Kubernetes, you should be able to access all the logs, and be able to reach any ports of the pods that are getting launched. In addition, you should be familiar with provisioning storage. + +In self-hosted environments, you are expected to have the ability to troubleshoot network issues, firewalls and hostnames. You will also have to configure and setup certificates for components to talk to each other securely. This topic will not be covered in this guide. In addition, you are expected to perform all other sysadmin work related to provisioning, resource allocation, etc. + +Vitess is capable of running on a variety of platforms. They may be self-hosted, in the public cloud, or in a cloud orchestration environment like Kubernetes. + +In this guide, we will assume that we are deploying in a self-hosted environment that has multiple data centers. This setup allows us to better understand the interaction between the components. + +Before starting, we assume that you have downloaded Vitess and finished the [Get Started](../../../get-started) tutorial. + +## External tools + +Vitess relies on two external components, and we recommend that you choose them upfront: + +1. [TopoServer](../../../concepts/topology-service/): This is the server in which Vitess stores its metadata. We recommend etcd if you have no other preference. +2. [MySQL](../../../overview/supported-databases/): Vitess supports MySQL/Percona Server 5.7 to 8.0. We recommend MySQL 8.0 for new installations. + +In this guide, we will be covering the case where the MySQL instances are managed by Vitess. A different section covers the details of running against [externally managed databases](../../configuration-advanced/unmanaged-tablet). + +## Provisioning + +Some high level decisions have to be made about the number of cells you plan to deploy on. This will loosely tie into how many replicas you intend to run per MySQL primary. You are likely to deploy at least one replica per cell. + +Vitess resource consumption is mostly driven by QPS, but there may be variations depending on your use case. As a starting point, you can use a rule of thumb of provisioning about 1 CPU for every 1000QPS. This CPU will be divided between MySQL, vttablets and vtgates, about 1/3 each. As for memory, you can start with approximately 1GB per CPU provisioned for Vitess components. MySQL memory will be largely guided by the buffer pool size, which may take some trial and error or prior experience to tune. + +Resources for other servers like the toposerver, vtctld, Vtadmin and VTOrc are minimal. They are likely not going to exceed one CPU per server instance. + +## Environment variables + +Setting up a few environment variables upfront will improve the manageability of the system: + +* `VTDATAROOT`: Setting up this value will make Vitess create the MySQL data files under this directory. Other Vitess binaries will also use this variable to locate such files as needed. If not specified, the default value is `/vt`. Typically, no other files get stored under this directory. However, many idiomatic deployments tend to reuse this as root directory for other purposes like log files, etc. +* `VT_MYSQL_ROOT`: Informs Vitess about where to find the `mysqld` binary. If this is not specified, Vitess will try to find `mysqld` in the current `PATH`. + +Vitess will automatically detect the flavor of MySQL and will adjust its behavior accordingly. You can override this behavior by specifying an explicit flavor with the `--db_flavor` command line argument to the various components. + +## Backups + +Backups will need to be shared across vttablet instances and multiple cells. You need to plan and allocate shared storage that must be accessible from all cells. Depending on the choice made, you will need to prepare a group of command line arguments to include with the Vitess components to launch. Here is an example: + +```text +--backup_storage_implementation file --file_backup_storage_root +``` + +{{< warning >}} +When using the file backup storage engine the backup storage root path must be on shared storage to provide a global view of backups to all vitess components. +{{< /warning >}} + +Please refer to the [Backup and Restore](../../operating-vitess/backup-and-restore) guide for instructions on how to configure other storage options. + +To avoid repetition we will use `` in our examples to signify the above flags. + +## Logging + +Vitess servers write to log files, and they are rotated when they reach a maximum size. It’s recommended that you run at INFO level logging. The information printed in the log files can come in handy for troubleshooting. You can limit the disk usage by running cron jobs that periodically purge or archive them. + +All Vitess servers accept a `--log_dir` argument and will create the log files in that specified directory. For example: + +```text +--log_dir=${VTDATAROOT}/tmp +``` diff --git a/content/en/docs/19.0/user-guides/configuration-basic/ports.md b/content/en/docs/19.0/user-guides/configuration-basic/ports.md new file mode 100644 index 000000000..a725b3eef --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/ports.md @@ -0,0 +1,53 @@ +--- +title: Ports +weight: 16 +aliases: ['/docs/launching/server-configuration/', '/docs/user-guides/server-configuration/', '/docs/user-guides/configuring-components/'] +--- +# Ports and Network interactions in Vitess + +Many/most of these ports are fully configurable, but we are listing their +defaults or the defaults we use in examples here. Your +environment may differ considerably, depending on your configuration options +for the various components: + + * Data path: + * Main query path: + * application → vtgate + * TCP port 3306 or 15306 (MySQL) + * TCP port 15999 (gRPC) + * vtgate → vttablet + * TCP port 16000 + vttablet UID (gRPC); e.g port 16100 for UID 100 + * vttablet → MySQL + * local Unix domain socket (if MySQL is local) + * TCP port 3306 (if MySQL is remote) + * vttablet → vttablet: vreplication within or across shards + * TCP port 16000 + vttablet UID (gRPC); e.g port 16100 for UID 100 + * MySQL → MySQL: within-shard replication + * TCP port 3306 (MySQL protocol) + * Control or meta-data paths: + * vtctld → vttablet + * TCP port 16000 + vttablet UID (gRPC); e.g port 16100 for UID 100 + * vtctldclient → vtctld + * TCP port 15999 (gRPC) + * vtadmin → + * TCP port 14200 (gRPC and HTTP) + * vtgate → topology server + * Depends on topology server, e.g.: + * for etcd typically TCP port 2379 + * for consul typically TCP port 8502 + * for zookeeper typically TCP port 2888 + * administrator using web browser → vtgate web UI + * TCP port 15001 (HTTP) + * administrator using web browser → vttablet web UI + * TCP port 15000 + vttablet UID (HTTP); e.g port 15100 for UID 100 + * administrator using web browser → vtadmin web UI + * TCP port 14201 (HTTP) + * administrator using web browser → vtorc web UI + * TCP port 16000 (HTTP) + * Metrics scraper (e.g. Prometheus) → vtgate web port + * TCP port 15001 (HTTP) + * Metrics scraper (e.g. Prometheus) → vttablet web port + * TCP port 15000 + vttablet UID (HTTP); e.g port 15100 for UID 100 + * Metrics scraper (e.g. Prometheus) → vtctld web port + * TCP port 15000 (HTTP) + diff --git a/content/en/docs/19.0/user-guides/configuration-basic/reparenting.md b/content/en/docs/19.0/user-guides/configuration-basic/reparenting.md new file mode 100644 index 000000000..abdd28b38 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/reparenting.md @@ -0,0 +1,22 @@ +--- +title: Reparenting +weight: 13 +--- + +Once you have the cluster up and running, you should perform a trial failover using `PlannedReparentShard` to make sure it works as expected. + +A typical use case for `PlannedReparentShard` is to use it during software updates. The command has a convenient `avoid_tablet` flag that allows you to specify the current vttablet you are going to perform maintenance on. If that is a primary, then it performs a failover to another eligible replica. Otherwise, it is a no-op. + +You can also perform a "Planned Reparent" through the browser from the VTAdmin Dashboard. + +![vtadmin-reparenting](../img/vtadmin-reparenting.png) + +{{< info >}} +The Vitess operator performs this step automatically when a container is gracefully brought down by Kubernetes, which also takes care of the use case of a software rollout. If a container or pod is brought down abruptly or crashes, then the primary will be unavailable until Kubernetes restarts it. However, if VTOrc is also deployed, it will detect this and failover to another eligible replica as the primary. VTOrc will not intervene during a graceful shut down. +{{< /info >}} + +For more information, please refer to the [Reparenting](../../configuration-advanced/reparenting) section. + +{{< info >}} +A reparenting operation can fail in the middle. If so, it is possible for the system to be in a situation where two vttablets report themselves as primary. If this happens, the one with the newer timestamp wins. The vtgates will automatically treat the newer primary as authoritative. The system will eventually heal itself because the vttablets use a registration protocol via the global topo and the older tablet will demote itself to a replica when it notices that it is no longer the primary. +{{< /info >}} diff --git a/content/en/docs/19.0/user-guides/configuration-basic/troubleshooting.md b/content/en/docs/19.0/user-guides/configuration-basic/troubleshooting.md new file mode 100644 index 000000000..15b3c4ec9 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/troubleshooting.md @@ -0,0 +1,168 @@ +--- +title: Troubleshooting +weight: 17 +--- + +## Understanding the Components + +The secret to troubleshooting a Vitess cluster well comes from knowing how all the components are wired together. + +Of these connections, the most important one is the query serving path: + +* The application sends a request to a vtgate. +* The vtgate forwards that request to one or more vttablets. +* The vttablets in turn send the request to MySQL. + +If there is any kind of problem with serving queries, these are the components to drill into. + +VTGates and vttablets connect to the global and cell-specific toposerver. They use these toposervers to broadcast their state as well as to discover configuration changes. Additionally, vtgates receive health information from the vttablets they are connected to, and use this information to direct traffic in real-time. If there is any kind of problem with configuration, these are the areas to focus on. + +The first step to troubleshooting is to have an established baseline. It is recommended that monitoring is set up for all the components as directed in the monitoring section. When there is an incident, the change in the graphs will likely help with identifying the root cause. + +## Query Serving + +Most of the focus of Vitess monitoring centers around the cost of a query. Although not always true, we use the following rules of thumb to get a rough estimate: + +* In MySQL, the time taken by a query roughly translates to its actual cost. More often than not, the limiting factor is the number of disk IOPS. +* In Vitess components, the payload contributes to the cost. The limiting factor is most often the CPU, followed by memory. +* The cost of parsing and analyzing the input query has started to become significant. This is typically driven by the size and complexity of the query. + +Let us now go through some fire drills. + +### Too many connections + +If you see an error that contains the string `Too many connections (errno 1040) (sqlstate 08004)`, then it means that the maximum number of connections allowed by MySQL has been exceeded. + +The remedy is to further increase the `max_connections` settings in MySQL. The other alternative is to reduce the pool sizes. As [recommended before](../vttablet-mysql/#starting-vttablet), the `max_connections` value should be set about double the number of connections allocated for pools. + +### Elevated Query Latency + +This is one of the most common problems. It can show up as just an elevated latency with no external impact. Sometimes, the problem can be more acute where queries return errors due to timeouts. There can be multiple root causes. + +#### Approach 1: Validate resource usage and remove bottlenecks + +Check vtgate CPU usage: If the vtgate CPU is too high or is getting throttled, it could be the root cause. Bringing up another vtgate to take on additional load or increasing the CPU quota of the VTGate should resolve the problem. + +Check vttablet CPU usage: If vttablet CPU usage is maxed out, the immediate solution is to increase the quota. If the vttablet is a replica, then bringing up more replicas should help distribute the load. If it is a primary, then you need to plan on splitting the shard into smaller parts, or reshard in the case of an unsharded keyspace. + +Check MySQL resource usage: If MySQL is resource constrained, for example IOPS, then you need to provision more. Also, you will then need to add more replicas or plan a reshard or split just like in the case of a vttablet. More often than not, MySQL will run into resource constraints before vttablet does. + +Check Network packet limits. Some cloud providers limit network capacity by limiting the number of packets per second. Check to see if this limit has been reached. If so, you will need to request a quota increase from the cloud provider. + +If none of the processes are resource constrained, the next step is to check connection pool waits in vttablet. If there are long waits, then we know that the connection pool is under-provisioned. Restarting the vttablets with increased pool sizes should fix the problem. + +If latency continues to be elevated after increasing the pool size, it most likely means that the contention has shifted from vttablet to MySQL. In that case, it is likely that MySQL is the one resource constrained. You may have to roll back the pool size increase and instead look at increasing resources for MySQL. + +#### Approach 2: Find the problematic query + +Typically, resource constraints are encountered during the early stages of a rollout where things are not tuned well. Once the system is well tuned and running smoothly, the root cause is likely to be related to how the application sends queries. + +We first need to determine if this is an overall increase in application traffic or a change in specific query patterns. + +Inspect the per-tablet and per-user graphs to see if the increase is uniform across all tables or is to only a specific table. + +If the increase is across the board, then it is likely a general overload. The mitigation is to increase provisioning or address the root cause of the overload if it was not expected. + +If the increase is on a specific table, then this data itself is sufficient to determine the root cause. If not, we may need to drill down further to identify if a specific query is causing the problem. There are two approaches: + +* Inspect the `/queryz` page and look at the stats for all queries of that table. It is very likely that the problematic ones have already risen to the top of the page and may be color-coded red. If not, talking a few snapshots of the page and comparing the stats should help identify the problematic query. +* Real-time stream from `/debug/querylog`, filtering out unwanted tables and observing the results to identify the problematic query. + +Once the query is identified, the remedy depends on the situation. It could be a rewrite of the query to be more efficient, the creation of an additional index, or it could be the shutdown of an abusive batch process. + +The above guidelines have not required you to inspect MySQL. Over time, Vitess has evolved by improving its observability every time there was an incident. However, there may still be situations where the above approach is insufficient. If so, you will need to resort to looking inside MySQL to find out the root cause. + +The actual identification of the root cause may not be as straightforward as described above. Sometimes, an incident is caused by multiple factors. In such cases, using first principles of troubleshooting and understanding how the components communicate with each other may be the only way to get to the bottom of a problem. If you have exhausted all the recommendations given so far and still have not found the root cause, you may have to directly troubleshoot the problem at the MySQL level. + +### Elevated Error Rates + +The analysis for elevated error rates for read queries follows steps similar to elevated latency. You should essentially use the same drill down approach to identify the root cause. + +### Transaction timeouts + +Transaction timeouts manifest as the following errors: + +```text +ERROR 1317 (HY000): vtgate: http://sougou-lap1:15001/: vttablet: rpc error: code = Aborted desc = transaction 1610909864463057369: ended at 2021-01-17 10:58:49.155 PST (exceeded timeout: 30s) (CallerID: userData1) +``` + +If you see such errors, you may have to do one of the following: + +* Increase the transaction timeout in vttablet by setting a higher value for `queryserver-config-transaction-timeout`. +* Refactor the application code to finish the transaction sooner. + +It is recommended to minimize long running transactions in MySQL. This is because the efficiency of MySQL drastically drops as the number of concurrent transactions increases. + +### Transaction connection limit errors + +If you encounter errors that contain the following text: `transaction pool connection limit exceeded`, it means that your connection pool for transactions is full and Vitess timed out waiting for a connection. This issue can have multiple root causes. + +If your transaction load is just spiky, then you may just have to increase the pool timeout to make the transaction wait longer for a connection. This can be increased by setting the `queryserver-config-txpool-timeout` flag in vttablet. The default value is one second. + +It is also possible that you have underprovisioned the transaction pool size. If so, you can increase the size by changing the value for `queryserver-config-transaction-cap`. Note that it is risky to increase the pool size beyond the low hundreds because MySQL performance can drastically deteriorate if too many concurrent transactions are opened. + +Another possibility is that the application is unnecessarily keeping transactions open for too long thereby causing the pool to get full. To identify this, you can look at the vttablet logs. Every time the pool gets full, the list of transactions that were occupying those connections are printed out. Looking at those transactions should help you identify the root cause. This logging is throttled to prevent log spam. + +Frequent application crashes can also leave transactions open in the pool until timeout. Vitess tries to detect this situation and proactively rolls back such transactions, but it is not always reliable. If this is the case, the log file will contain many unfinished transactions that were rolled back. + +If you are starting to see these errors due to steady organic growth, it may be time to split the database or reshard. + +### Errant GTIDs + +An errant GTID incident is one where the MySQL instances of a shard do not agree on the events in the binlogs. This means that the data on those instances has potentially diverged. Errant GTIDs are often introduced due to operator errors. For example, someone could use DBA privileges to write data to a replica. + +In Vitess, you can get into an errant GTID situation if a primary is network partitioned and you make a decision to proceed forward with an `EmergencyReparentShard`. This will essentially cause the old primary to get indefinitely stuck due to transactions waiting for a semi-sync ack. The natural instinct would be to restart that server. However, such a restart will cause MySQL to go into recovery mode and complete those pending transactions thereby causing divergence. + +VTOrc can be used to detect errant GTIDs. You can also set up your own monitoring to detect this situation. This can be performed by ensuring that the GTIDs of the replicas are always a subset of the primary. + +If an errant GTID is detected, the first task is to identify the GTIDs that are diverged. If the divergence did not cause any data skew, you could choose to create dummy transactions with those extra GTIDs on instances that do not contain them. + +If the data has diverged, you have to make a decision about which one is authoritative. Once that is decided, it is recommended that you first take a backup of the instance that you have determined to be authoritative. Following this, you can bring down the instances that were non-authoritative and restart them with empty directories. This will trigger the restore workflow that will start with the authoritative backup. Once restored, the MySQL will point itself to the current primary and catch up to a consistent state. + +### Replica vttablet not receiving queries + +A number of reasons can cause a vtgate to not send queries to a replica vttablet. The first step is to visit the `/debug/status` page of vtgate and look at the `Health Check Cache` section. + +If the vttablet entry is present, but is color coded red and displays an error message, it means that vtgate is seeing the vttablet as unhealthy. Once you fix the error that causes the problem, traffic should resume to the vttablet. There can be many reasons for the unhealthiness: + +* vttablet may not be reachable: troubleshoot connectivity from the vtgate machine to the vttablet, make sure firewall rules allow access, ports are reachable, etc. +* vttablet is reporting itself as unhealthy: Fix the root cause. For example, the MySQL may be lagging too much, or vttablet may have trouble connecting to the MySQL instance, etc. + +If the vttablet entry is absent, then it means that vtgate has not discovered the vttablet yet. Check to see if vtgate is having trouble connecting to the topo server. If there was a problem, there should be errors in the log file like `cannot get tablets`. If such errors are found, fix the root cause and verify again. + +It may be worth proactively monitoring `TopologyWatcherErrors` and `TopologyWatcherOperations`. Alerting on errors can help identify these problems early. + +If there are no topo errors in vtgate, check to see if the tablet record has been created by vttablet using the `vtctldclient GetTablets` command. If the tablet record is absent or does not contain the correct host and port info, check the vttablet logs to see if it has trouble connecting to the topo and is unable to publish its existence. If there are errors, fixing the issue should resolve the problem. + +### Read-only errors + +If you see the following error string `The MySQL server is running with the --read-only option so it cannot execute this statement (errno 1290) (sqlstate HY000)` while trying to write to the primary, then it likely means that a previous `PlannedReparentShard` operation failed in the middle. + +Re-executing `PlannedReparentShard` against that primary should fix the problem. If this operation fails with an error saying that there is no current primary, you may have to issue an `EmergencyReparentShard` to safely elect a primary. + +If VTOrc is running, no action is needed because VTOrc will notice this state and fix it in a safe manner. + +This error can also be encountered if a new primary has been elected, but the older vttablet continues to think that it is still the primary. If this is the situation, then it is transient and will heal itself as long as components are able to communicate with each other. In this situation, the older vttablet will be in read-only mode. VTGates that are trying to send the writes to it will fail. + +Eventually, the new primary will inform the vtgates of its existence, and they will start sending traffic to the new primary instead of the old one. The old primary will also eventually notice that a new primary was elected. When it notices it, it will demote itself to a replica. + +### Local TopoServer of a Cell is getting overloaded + +This situation can happen if a large number of vtgates continuously spam the local toposerver to check for changes in the list of tablet servers. If this is the case, you may have to reduce the polling frequency of the vtgates by reducing the `--tablet_refresh_interval` value. + +### Global Topo or Cell Topo is down + +Vitess servers are built to survive brief topo outages in the order of many minutes. All Vitess servers cache the necessary information to serve traffic. If there is an outage, they use the cached information to continue serving traffic. + +However, during such an outage, you may not be able to perform cluster maintenance operations like a reparent, resharding, or bringing up new servers. + +### Topo Complete Data Loss + +In the unforeseen circumstance of a total data loss of the topo servers, a Vitess cluster can be restored to an operational state by performing the following actions: + +* Bring up a brand new set of empty topo servers. +* Recreate the cell info as before. +* Restart all the vttablets. +* Upload the VSchema for the recreated keyspaces. + +If you are in the middle of a reshard, make sure you restart the source vttablets first. This order will ensure that they get marked as serving. Any shards that get added later that overlap with existing keyranges will be marked as non-serving. 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 new file mode 100644 index 000000000..9ca987558 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/vtctld.md @@ -0,0 +1,41 @@ +--- +title: vtctld +weight: 5 +--- + +vtctld is not required to be highly available because it is not in the serving path of a query. Nevertheless, it may be wise to bring up more than a single instance. Typically, users bring up one instance per cell. + +Even if brought up within each cell, vtctld itself is not tied to that cell. It will attempt to access all servers of all cells. You can bring up vtctld with the following invocation: + +```sh +vtctld \ + --log_dir=${VTDATAROOT}/tmp \ + --port=15000 \ + --grpc_port=15999 \ + --service_map='grpc-vtctl,grpc-vtctld' +``` + +If the TopoServer is unreachable, or if the topo flags are incorrectly configured, vtctld will fail to start. You may see an error message like the following in the logs: + +```text +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`. +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. + +## vtctldclient + +Since we will be using `vtctldclient` often, it will be convenient to configure an alias for it: + +```sh +alias vtctldclient="command vtctldclient --server " +``` + +{{< info >}} +We intend to move these arguments into an init file. Once that is done, there will be no need to set up the alias any more. +{{< /info >}} + +The next step will be to create a cell. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/vtgate.md b/content/en/docs/19.0/user-guides/configuration-basic/vtgate.md new file mode 100644 index 000000000..6d0357958 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/vtgate.md @@ -0,0 +1,104 @@ +--- +title: vtgate +weight: 11 +--- + +VTGates are the primary interface to the application. They do not have any persistent state. You can bring up as many vtgates as necessary. An application can connect to any vtgate to get access to all the servers within a cell. We recommend configuring a load balancer to distribute traffic between them. A typical rule of thumb would be to bring up as many vtgates as there are vttablets. + +It is better to bring up multiple vtgates within a single machine rather than trying to run a single instance that tries to use all the resources. This approach enables better amortization of Go’s garbage collector. + +You can bring up the vtgates before creating any keyspaces or bringing up vttablets. The advantage of bringing up the vtgates last is that it allows them to immediately discover the existing vttablets. Otherwise, it will take up to one polling cycle before they are discovered. The default value for this flag (`--tablet_refresh_interval`) is one minute. If you intend to reduce this value, ensure that the increased polling frequency will not overwhelm the toposerver. + +VTGate requires a cell to operate in. A vtgate’s main job is to forward requests to the vttablets in the local cell. However, vtgates can go cross-cell in two situations: + +* vtgate receives queries to the primary, and the primary is not in the current cell. +* vtgate was configured to go to other cells in case no local vttablets were available. + +Here is a sample vtgate invocation: + +```text +vtgate \ + --log_dir=${VTDATAROOT}/tmp \ + --cell=cell1 \ + --cells_to_watch=cell1 \ + --tablet_types_to_wait=PRIMARY,REPLICA \ + --port=15001 \ + --mysql_server_port=15306 \ + --mysql_auth_server_impl=static \ + --mysql_auth_server_static_file=mysql_creds.json \ + --grpc_port=15991 \ + --service_map='grpc-vtgateservice' \ + --vschema_ddl_authorized_users='dba%' +``` +VTGate uses the global topo to get the topo addresses of the cells it has to watch. For this reason, you do not need to specify the topo addresses for the current cell. + +VTGate does not require ``. + +For sending primary queries across cells, you must specify an additional `cells_to_watch` flag. This will make the vtgates watch those additional cells, and will allow them to keep track of the primaries in those cells. + +The `cells_to_watch` flag is a required parameter and must at least include the current cell. This is an [issue](https://github.com/vitessio/vitess/issues/6126) we will fix soon. + +Going cross-cell for non-primary requests is an advanced use case that requires setting up cell aliases. This topic will not be covered in this user guide. + +For those who wish to use the MySQL protocol, you must specify a `mysql_server_port` and a `mysql_auth_server_impl` for configuring authentication. Predefined auth servers are `clientcert`, `static`, `ldap` and `none`. The most commonly used authentication is `static` that allows you to specify the credentials through a `mysql_auth_server_static_file` parameter. + +The `vschema_ddl_authorized_users` specifies which users can alter the vschema by issuing “[vschema ddls](../../vschema-guide/vschema_ddl)” directly to vtgate. VSchema DDL is an experimental feature. + +Here are the contents of an example file that shows the ability to specify MySQL native passwords as well as plain text: + +```json +{ + "mysql_user": [ + { + "MysqlNativePassword": "*9E128DA0C64A6FCCCDCFBDD0FC0A2C967C6DB36F", + "Password": "mysql_password", + "UserData": "mysql_user" + } + ], + "mysql_user2": [ + { + "Password": "mysql_password", + "UserData": "mysql_user" + } + ], + "mysql_user3": [ + { + "MysqlNativePassword": "*9E128DA0C64A6FCCCDCFBDD0FC0A2C967C6DB36F", + "UserData": "mysql_user" + } + ] +} +``` + +For those who wish to use the Java or Go grpc clients to vtgate, you must also configure `grpc_port` and specify the service map as `service_map='grpc-vtgateservice'`. Note that the MySQL protocol support for `VStream` feature is currently experimental. + +You can also set the following flags to control load-balancing for replicas: + +* `discovery_high_replication_lag_minimum_serving`: If the replication lag of a vttablet exceeds this value, vtgate will treat it as unhealthy and will not send queries to it. This value is meant to match vttablet’s `unhealthy_threshold` value. +* `discovery_low_replication_lag`: If a single vttablet lags beyond this value, vtgate will not send it any queries. However, if too many replicas exceed this threshold, then vtgate will send queries to the ones that have the least lag. A weighted average algorithm is used to exclude the outliers. This value is meant to match vttablet’s `degraded_threshold` value. + +A vtgate that comes up successfully will show all the vttablets it has discovered in its `/debug/status` page under the `Health Check Cache` section. + +![vtgate-healthy-tablets](../img/vtgate-healthy-tablets.png) + +If vtgates cannot connect to one of the vttablets it discovered from the topo, or if the vttablet is unhealthy, it will be shown in red in the `Health Check Cache`, and a corresponding error message will be displayed next to it: + +![vtgate-partially-healthy-tablets](../img/vtgate-partially-healthy-tablets.png) + +You can verify that the vtgates came up successfully by using the MySQL client: + +```text +~/...vitess/examples/local> mysql -h 127.0.0.1 -P 15306 --user=mysql_user --password=mysql_password +[snip] +mysql> show databases; ++----------+ +| Database | ++----------+ +| commerce | ++----------+ +1 row in set (0.00 sec) +``` + +The `show databases` command presents the `commerce` keyspace as a database. Under the covers, the MySQL database backing it is actually `vt_commerce`. + +Congratulations! You have successfully brought up a Vitess cluster. diff --git a/content/en/docs/19.0/user-guides/configuration-basic/vtorc.md b/content/en/docs/19.0/user-guides/configuration-basic/vtorc.md new file mode 100644 index 000000000..cdaca04e1 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/vtorc.md @@ -0,0 +1,46 @@ +--- +title: VTOrc +weight: 8 +--- + +VTOrc is the automated fault detection and repair tool of Vitess. It started off as a fork of the [Orchestrator](https://github.com/openark/orchestrator), which was then custom-fitted to the Vitess use-case running as a Vitess component. +An overview of the architecture of VTOrc can be found on this [page](../../../reference/vtorc/architecture). + +Setting up VTOrc lets you avoid performing the `InitShardPrimary` step. It automatically detects that the new shard doesn't have a primary and elects one for you. + + +### Flags + +For a full list of supported flags, please look at [VTOrc reference page](../../../reference/programs/vtorc). + +### UI, API and Metrics + +For information about the UI, API and metrics that VTOrc exports, please consult this [page](../../../reference/vtorc/ui_api_metrics). + +### Example invocation of VTOrc + +You can bring VTOrc using the following invocation: + +```sh +vtorc --topo_implementation etcd2 \ + --topo_global_server_address "localhost:2379" \ + --topo_global_root /vitess/global \ + --port 15000 \ + --log_dir=${VTDATAROOT}/tmp \ + --recovery-period-block-duration "10m" \ + --instance-poll-time "1s" \ + --topo-information-refresh-duration "30s" \ + --alsologtostderr + ``` + +You can optionally add a `clusters_to_watch` flag that contains a comma separated list of keyspaces or `keyspace/shard` values. If specified, VTOrc will manage only those clusters. + + +### Durability Policies + +All the failovers that VTOrc performs will be honoring the [durability policies](../../configuration-basic/durability_policy). Please be careful in setting the +desired durability policies for your keyspace because this will affect what situations VTOrc can recover from and what situations will require manual intervention. + +### Running VTOrc using the Vitess Operator + +To find information about deploying VTOrc using Vitess Operator please take a look at this [page](../../../reference/vtorc/running_with_vtop). diff --git a/content/en/docs/19.0/user-guides/configuration-basic/vttablet-mysql.md b/content/en/docs/19.0/user-guides/configuration-basic/vttablet-mysql.md new file mode 100644 index 000000000..1f5b25e38 --- /dev/null +++ b/content/en/docs/19.0/user-guides/configuration-basic/vttablet-mysql.md @@ -0,0 +1,219 @@ +--- +title: VTTablet and MySQL +weight: 8 +--- + +Let us assume that we want to bring up a single unsharded keyspace. The first step is to identify the number of replicas (including the primary) we would like to deploy. We should also make a decision about how to distribute them across the cells. + +Vitess requires you to assign a globally unique id (tablet UID) to every vttablet. This has to be an unsigned 32-bit integer. This is a legacy requirement derived from the fact that the MySQL server id (also an unsigned 32-bit integer) used to be the same as the tablet uid. This is not the case any more. + +In terms of mapping these components to machines, Vitess allows you to run multiple of these on the same machine. If this is the case, you will need to assign non-conflicting ports for these servers to listen on. + +VTTablet and MySQL are meant to be brought up as a pair within the same machine. By default, vttablet will connect to its MySQL over a unix socket. + +Let us look at the steps to bring up the first pair for an unsharded keyspace `commerce` in cell1 and a tablet uid of 100. + +## Starting MySQL + +`mysqlctl` is a convenience wrapper that can bring up and initialize a fresh MySQL server, and isolate all associated files within directories that are tied to the unique UID. This makes it easy to bring up multiple MySQL instances on the same machine. + +The necessary arguments to a `mysqlctl` are the `tablet_uid` and `mysql_port`. Here is a sample invocation: + +```sh +mysqlctl \ + --log_dir=${VTDATAROOT}/tmp \ + --tablet_uid=100 \ + --mysql_port=17100 \ + init +``` + +### my.cnf + +`mysqlctl` **will not** read configuration files from common locations such as `/etc/my.cnf` or `/etc/mysql/my.cnf`. Instead, it will create a separate `my.cnf` config file using builtin defaults. The source files can be found [here](https://github.com/vitessio/vitess/tree/main/config/mycnf). To add your own settings, you can set the `EXTRA_MY_CNF` environment variable to a list of colon-separated files. Alternatively, you can override the default behavior by specifying your own template file using the `-mysqlctl_mycnf_template` command line argument. + +For example, to override the default innodb buffer pool size, you would create a file named `/path/to/common.cnf` as follows: +```text +innodb_buffer_pool_size=1G +``` + +And then launch mysqlctl with as follows: + +```sh +EXTRA_MY_CNF=”/path/to/common.cnf” mysqlctl \ + --log_dir=${VTDATAROOT}/tmp \ + --tablet_uid=100 \ + --mysql_port=17100 \ + init +``` + +When specifying additional configuration changes to Vitess, please keep in mind that changing the following settings is unsupported: + +| Setting | Reason | +|---------------------|----------------| +| `auto_commit` | MySQL autocommit needs to be turned on. VTTablet uses connection pools to MySQL. If autocommit is turned off, MySQL will start an implicit transaction (with a point in time snapshot) for each connection and will work very hard at keeping the current view unchanged, which would be counter-productive. | +| `log-bin` | Several Vitess features rely on the binary log being enabled. | +| `binlog-format` | Vitess only supports row-based replication. Do not change this setting from the included configuration files. | +| `binlog-row-image` | Vitess only supports the default value (`FULL`) | +| `log-slave-updates` | Vitess requires this setting enabled, as it is in the included configuration files. | +| `character-set\*` | Vitess only supports `utf8` (and variants such as `utf8mb4`) | +| `gtid-mode` | Vitess relies on GTIDs to track changes to topology. | +| `gtid-strict-mode`/`enforce-gtid-consistency` | Vitess requires this setting to be unchanged. | + +Support was recently added to override `sql_mode`. However, we recommend keeping `STRICT_TRANS_TABLES` or replacing it with`STRICT_ALL_TABLES`. Without one of these settings, MySQL could truncate values at the time of writing, and this can mismatch with decisions made by the sharding logic and lead to data corruption. VTTablet ensures that one of these values is set. If absolutely necessary, you can override this check by setting `-enforce_strict_trans_tables=false` while invoking vttablet. + +### init\_db.sql + +After mysqld comes up, `mysqlctl` will initialize the server using an internal script, the contents of which can be found [here](https://github.com/vitessio/vitess/blob/main/config/init_db.sql). You can override this behavior by providing your own script using the `-init_db_sql_file` command line argument. + +### Disable AppArmor + +There is a common pitfall to watch out for: If you see an error like this in the mysqlctl logs, you may need to [disable AppArmor](../../../get-started/local/#disable-apparmor-or-selinux): + +```text +I0429 01:16:25.648506 1 mysqld.go:454] Waiting for mysqld socket file (/vtdataroot/tabletdata/mysql.sock) to be ready... +I0429 01:16:25.656153 1 mysqld.go:399] Mysqld.Start(1588122985) stderr: mysqld: [ERROR] Could not open required defaults file: /vtdataroot/tabletdata/my.cnf +I0429 01:16:25.656180 1 mysqld.go:399] Mysqld.Start(1588122985) stderr: mysqld: [ERROR] Fatal error in defaults handling. Program aborted! +I0429 01:16:25.657249 1 mysqld.go:418] Mysqld.Start(1588122985) exit: exit status 1 +``` + +Disabling AppArmor once may not be enough. Many software installs or upgrades automatically install it back. You may have to disable it again if this happens. + +### Verify MySQL + +You can verify that MySQL came up successfully by connecting to it from the command line client: + +```sh +$ mysql -S ${VTDATAROOT}/vt_0000000100/mysql.sock -u vt_dba +[snip] +mysql> show databases; ++--------------------+ +| Database | ++--------------------+ +| information_schema | +| _vt | +| mysql | +| performance_schema | +| sys | ++--------------------+ +5 rows in set (0.00 sec) +``` + +The MySQL instance that was brought up has no identity related to keyspace or shard at this moment. These will be assigned in subsequent steps. + +### mysqlctld + +`mysqlctld` is the server version of `mysqlctl`. If the target directories are empty when it is invoked, it automatically performs an `init`. The process can subsequently receive commands from vttablet to perform housekeeping operations like shutting down and restarting MySQL as needed. + +To enable communication with vttablet, the server must be configured to receive grpc messages on a unix domain socket: + +``` +mysqlctld \ + --log_dir=${VTDATAROOT}/tmp \ + --tablet_uid=100 \ + --mysql_port=17100 \ + --socket_file=/path/to/socket_file +``` + +When starting vttablet, the following additional flag must be specified: + +``` +--mysqlctl_socket=/path/to/socket_file +``` +## Starting vttablet + +VTTablet should be brought up on the same machine as the MySQL instance. It needs the following flags: + +* and . +* `tablet-path`: This should be the cell name followed by a `-` and the tablet UID used for `mysqlctl`. VTTablet will infer the `cell` name from this. Example: `cell1-100`. +* `init_keyspace`: The keyspace that the tablet is going to serve. This will cause a keyspace to be created if one is not present. +* `init_shard`: The shard that the tablet is going to serve. This will cause a shard to be created if one is not present. +* `init_tablet_type`: This will typically be REPLICA. You may use other tablet types like “RDONLY”. Note that you are not allowed to start a tablet as a "PRIMARY". +* `port`, `grpc_port`, and `--service_map` `'grpc-queryservice,grpc-tabletmanager'` + +There are some additional parameters that we recommend setting: + +* `enable_replication_reporter`: Enabling this flag will make vttablet send its replication lag information to the vtgates, and they will use this information to avoid sending queries to replicas that are lagged beyond a threshold. +* `unhealthy_threshold`: If `enable_replication_reporter` is enabled, and the replication lag exceeds this threshold, then vttablet stops serving queries. This value is meant to match the vtgate `discovery_high_replication_lag_minimum_serving` flag. +* `degraded_threshold`: This flag does not change vttablet’s behavior. This threshold is used to report a warning in the status page if the replication lag exceeds this threshold. This value is meant to match the vtgate `discovery_low_replication_lag` flag. +* `restore_from_backup`: This flag informs vttablet to automatically restore data from the latest backup. Once this task completes, vttablet will point itself at the current primary to catch up on replication. When that falls below the specified threshold, vtgate will automatically start sending queries to the tablet. +* `queryserver-config-pool-size`:This value should be set to the max number of simultaneous queries you want MySQL to run. This should typically be around 2-3x the number of allocated CPUs. Around 4-16. There is not much harm in going higher with this value, but you may see no additional benefits. This pool gets used if the workload is set to `oltp`, which is the default. +* `queryserver-config-transaction-cap`: This value should be set to how many concurrent transactions you wish to allow. This should be a function of transaction rate and transaction length. Typical values are in the low 100s. +* `queryserver-config-stream-pool-size`: This value is relevant only if you plan to run streaming queries using the `workload='olap'` setting. This value depends on how many simultaneous streaming queries you plan to run. Typical values are similar to `queryserver-config-pool-size`. +* `queryserver-config-query-timeout`: This value should be set to the upper limit you’re willing to allow an OLTP query to run before it’s deemed too expensive or detrimental to the rest of the system. VTTablet will kill any query that exceeds this timeout. This value is usually around 15-30s. +* `queryserver-config-transaction-timeout`: This value is meant to protect the situation where a client has crashed without completing a transaction. Typical value for this timeout is 30s. +* `queryserver-config-idle-timeout`: This value sets a time in seconds after which, if a connection has not been used, this connection will be removed from pool. This effectively manages number of connection objects and optimizes the pool performance. +* `queryserver-config-max-result-size`: This parameter prevents the OLTP application from accidentally requesting too many rows. If the result exceeds the specified number of rows, VTTablet returns an error. The default value is 10,000. + +Here is a typical vttablet invocation: + +```text +vttablet \ + --log_dir=${VTDATAROOT}/tmp \ + --cell=cell1 \ + --tablet-path=cell1-100 \ + --init_keyspace=commerce \ + --init_shard=0 \ + --init_tablet_type=replica \ + --port=15100 \ + --grpc_port=16100 \ + --service_map 'grpc-queryservice,grpc-tabletmanager’ \ + --enable_replication_reporter=true \ + --restore_from_backup=true \ + --queryserver-config-pool-size=16 \ + --queryserver-config-transaction-cap=300 \ + --queryserver-config-stream-pool-size= 16 +``` + +### Key configuration notes + +* It is important to set MySQL’s `max_connections` property to be 50%-100% higher than the total number of connections in the various pools. + * This is because Vitess may have to kill connections and open new ones. MySQL accounting has a delay in how it counts closed connections, which may cause its view of the number of connections to exceed the ones currently opened by Vitess. For example, in the above example, the `max_connections` settings should be around 800. +* It is also important to set vttablets `queryserver-config-idle-timeout` to be at least 10% lower than MySQL's `wait_timeout`. + * This is because MySQL's `wait_timeout` is the number of seconds the server waits for activity on a noninteractive connection before closing it. So if the vttablet setting is not lower the MySQL limit will be hit first and can cause issues with performance. The defaults are as follows: `queryserver-config-idle-timeout` defaults to 30 minutes and MySQL's `wait_timeout` defaults to 8 hours. + +It is normal to see errors like these in the log file until MySQL instances have been initialized and a vttablet has been elected as primary: + +```text +2020-04-27T00:38:02.040081Z 2 [Note] Aborted connection 2 to db: 'unconnected' user: 'root' host: 'localhost' (Got an error reading communication packets) +``` + +Starting the first vttablet against a keyspace and shard performs the following actions: + +* Create a keyspace and shard in the global topo if these did not exist before. +* Perform a [RebuildKeyspaceGraph](../../../reference/programs/vtctl/keyspaces/#rebuildkeyspacegraph) to deploy the global topo to the current cell (cell1). +* Create a tablet record, which will allow vtgates to discover it. +* No restore action will be performed because this is the first time vttablet is coming up and no backups exist yet. + +The vttablet will be unhealthy because the database for the keyspace has not been created. Visiting the `/debug/status` page on its port should show the following information: + +![unhealthy-tablet](../img/unhealthy-tablet.png) + +The next step is to bring up the rest of the vttablet-MySQL pairs on other machines or different ports of the same machine. + +## Tablet Records + +You can find out the current state of all vttablets with the following command: + +```sh +$ vtctldclient GetTablets +cell1-0000000100 commerce 0 primary sougou-lap1:15100 sougou-lap1:17100 [] 2021-01-02T22:27:11Z +cell1-0000000101 commerce 0 replica sougou-lap1:15101 sougou-lap1:17101 [] +cell1-0000000102 commerce 0 rdonly sougou-lap1:15102 sougou-lap1:17102 [] +``` + +This information is extracted from the “tablet record” in the cell specific topo. You can also browse to this information in VTAdmin either from the Tablets page or from the Topology page. + +![vtctld-tablet-list](../img/vtadmin-tablet-list.png) + +You can move a vttablet-MySQL pair to a new host after shutting them down on the current host. Bringing up the new pair with the same UID will update the tablet record with the new address and ports. This will be noticed by the vtgates and they will adjust their traffic accordingly. However, you must not move a tablet to another cell. + +Gracefully bringing down a vttablet will remove the address information from the tablet record thereby informing the vtgates that they should not attempt to send any more traffic to the tablets. + +If a vttablet crashes, the address info will remain in the topo. However, vtgates will notice that the tablet is not reachable and will remember it as unhealthy. They will keep attempting to contact the tablet until it comes back up as healthy. + +It is recommended that you delete the tablet record if you intend to bring down a vttablet permanently. The command to delete a tablet is: + +```text +vtctldclient DeleteTablets cell1-100 +``` + diff --git a/content/en/docs/19.0/user-guides/migration/_index.md b/content/en/docs/19.0/user-guides/migration/_index.md new file mode 100644 index 000000000..1a3474b3d --- /dev/null +++ b/content/en/docs/19.0/user-guides/migration/_index.md @@ -0,0 +1,5 @@ +--- +title: Migration +description: User guides covering data migrations into Vitess +weight: 3 +--- diff --git a/content/en/docs/19.0/user-guides/migration/materialize.md b/content/en/docs/19.0/user-guides/migration/materialize.md new file mode 100644 index 000000000..eaeaa7f68 --- /dev/null +++ b/content/en/docs/19.0/user-guides/migration/materialize.md @@ -0,0 +1,355 @@ +--- +title: Materialize +weight: 3 +aliases: ['/docs/user-guides/materialize/'] +--- + +{{< info >}} +This guide follows on from the [Get Started](../../../get-started/) guides. Please make sure that you have a +[Kubernetes Operator](../../../get-started/operator) or [local](../../../get-started/local) installation ready. +Make sure you have only run the "101" step of the examples, for example `101_initial_cluster.sh` in the +[local](../../../get-started/local) example. The commands in this guide also assume you have setup the shell +aliases from the example, e.g. `env.sh` in the [local](../../../get-started/local) example. +{{< /info >}} + +[`Materialize`](../../../reference/vreplication/materialize/) is a VReplication command/workflow. It can be used as a more +general way to achieve something similar to [MoveTables](../../../concepts/move-tables) or as a way to generate +[materialized views](https://en.wikipedia.org/wiki/Materialized_view) of a table (or set of tables) in the same or +different keyspace from the source table (or set of tables). In general, it can be used to create and maintain +continually updated [materialized views](https://en.wikipedia.org/wiki/Materialized_view) in Vitess, without having +to resort to manual or trigger-based population of the view content. + +Since [`Materialize`](../../../reference/vreplication/materialize/) uses VReplication, the view can be kept up-to-date +in very close to real-time which enables use-cases like creating copies of the same table that are sharded in +different ways for the purposes of avoiding expensive cross-shard queries. `Materialize` is also flexible enough to +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 +[`Materialize`](../../../reference/vreplication/materialize). + +Let's start by loading some sample data: + +```bash +$ mysql < ../common/insert_commerce_data.sql +``` + +We can look at what we just inserted: + +```bash +$ mysql --table < ../common/select_commerce_data.sql + +Using commerce +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 4 | dan@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +Product ++----------+-------------+-------+ +| sku | description | price | ++----------+-------------+-------+ +| SKU-1001 | Monitor | 100 | +| SKU-1002 | Keyboard | 30 | ++----------+-------------+-------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 4 | 4 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ +``` + +Note that we are using `commerce` keyspace. + +## Planning to Use Materialize + +In this scenario, we are going to make two copies of the `corder` table **in the same `commerce` keyspace** using +the table names of `corder_view` and `corder_view_redacted`. The first copy will be identical to the source table, but +for the `corder_view_redacted` copy we will use the opportunity to drop or redact the `price` column. + +## Create the Destination Tables + +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) +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: + +```sql +$ cat <}} +While this deletes the `Materialize` VReplication stream, the actual source and target tables are left unchanged +and in the same state they were at the moment the VReplication stream was deleted. +{{}} diff --git a/content/en/docs/19.0/user-guides/migration/migrate-data.md b/content/en/docs/19.0/user-guides/migration/migrate-data.md new file mode 100644 index 000000000..752248093 --- /dev/null +++ b/content/en/docs/19.0/user-guides/migration/migrate-data.md @@ -0,0 +1,71 @@ +--- +title: Migrating Data Into Vitess +weight: 1 +aliases: ['/docs/user-guides/migrate-data/'] +--- + +# Introduction + +There are two main parts to migrating your data to Vitess: migrating the actual data and repointing the application. This page will focus primarily on the methods that can be used to migrate *your data* into Vitess. + +## Overview + +There are different methods to migrate your data into Vitess. Choosing the appropriate option depends on several factors: +1. The nature of the application accessing the MySQL database +1. The size of the MySQL database to be migrated +1. The load, especially the write load, on the MySQL database +1. Your tolerance for downtime during the migration of data +1. Whether you require the ability to reverse the migration if needed +1. The network level configuration of your components + +The two primary methods are: + +* Dump and Restore +* VReplication (**Recommended**) + +## Dump and Restore + +{{< warning >}} +This method likely isn’t viable for most production applications as it will incur significant application downtime. +{{}} + +The simplest method to migrate data is to do a data dump and restore (AKA "stop-the-world"). For this we recommend using [`mysqldump`](https://dev.mysql.com/doc/refman/en/mysqldump.html) or +[`go-mydumper`](https://github.com/aquarapid/go-mydumper). To execute this method you would follow these steps: +1. Stop writing to the source MySQL database +1. Take a logical dump of the database +1. Apply any simple transformations on the output if needed +1. Import the data into Vitess via the frontend [Vitess Gateway](../../../concepts/vtgate/) (`vtgate`) +1. Repoint your application to the new database via a [Vitess Gateway](../../../concepts/vtgate/) and resume writing + +This method is only suitable for migrating small or non-critical databases that can tolerate downtime. The database will be unavailable for writes between the time the dump is started and the time the restore of the dump is completed. For databases of 10’s of GB and up this process could take hours or even days. The amount of downtime scales with the amount of data being migrated. + +## VReplication + +Vitess provides the [`MoveTables`](../../../reference/vreplication/movetables/) command which allows you to perform +fully online data migrations into Vitess with the ability to (temporarily) revert the migration if needed — all +without incurring application downtime. + +An ["unmanaged Vitess tablet"](../../configuration-advanced/unmanaged-tablet/) will be placed in front of your existing MySQL database. This tablet will then be the bridge that allows you to migrate the data into Vitess. This unmanaged tablet ([`vttablet`](../../../reference/programs/vttablet/)) must be able to communicate with your new Vitess cluster over the network. + +This method uses a combination of transactional SELECTs and filtered MySQL replication to safely and accurately copy each +of the tables in the source database to Vitess without disrupting normal traffic to your existing database. Once all the +data is copied, the two databases are then kept in sync using a replication stream from the source database. You can +verify that the source and destination are fully in sync using [`VDiff`](../../../reference/vreplication/vdiff/) command +and perform final testing on the Vitess keyspace before cutting over your application traffic. + +Once your testing has completed, application traffic can be moved from the source MySQL database itself and switched to the Vitess cluster's [`vtgate`](../../../reference/programs/vtgate/) instance(s). For this switch, a small amount of downtime will likely be necessary. This downtime could be seconds or minutes, depending on the application and application automation. + +Once your application traffic is going to Vitess — while your original MySQL instance is still serving the queries — you can prepare to fully cutover all traffic and query serving using the [`SwitchTraffic`](../../../reference/vreplication/movetables/#switchtraffic) action. This will cause the Vitess cluster to start serving all traffic for the tables that were migrated. At this point the VReplication workflow automatically reverses and the original MySQL instance is automatically kept in sync with Vitess. Once the switch is complete and you have confirmed that everything is working +correctly you can complete the migration using the [`Complete`](../../../reference/vreplication/movetables/#complete) +action and the original MySQL instance can be shut down. If for any reason you need to reverse the migration, you +can use the [`ReverseTraffic`](../../../reference/vreplication/movetables/#reversetraffic) action to switch back to +serving data from the original MySQL instance before later attempt another cutover using [`SwitchTraffic`](../../../reference/vreplication/movetables/#switchtraffic). + +{{< info >}} +If you require transforming your data while migrating it into Vitess then the [`Materialize`](../../../reference/vreplication/materialize/) command offers an alternative to [`MoveTables`](../../../reference/vreplication/movetables/). +{{}} + +The remaining pages in this guide walk you through an example of the key steps for this native Vitess migration process: +1. [Moving the tables](../move-tables/) +2. [Materializing data if needed](../materialize/) +3. [Troubleshooting](../troubleshooting/) 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 new file mode 100644 index 000000000..26bb24ae9 --- /dev/null +++ b/content/en/docs/19.0/user-guides/migration/move-tables.md @@ -0,0 +1,700 @@ +--- +title: Move Tables +weight: 2 +aliases: ['/docs/user-guides/move-tables/'] +--- + +{{< info >}} +This guide follows on from the [Get Started](../../../get-started/) guides. Please make sure that you have an +[Kubernetes Operator](../../../get-started/operator) or [local](../../../get-started/local) installation ready. +Make sure you have only run the "101" step of the examples, for example `101_initial_cluster.sh` in the +[local](../../../get-started/local) example. The commands in this guide also assume you have setup the shell +aliases from the example, e.g. `env.sh` in the [local](../../../get-started/local) example. +{{< /info >}} + +[MoveTables](../../../concepts/move-tables) is a [VReplication](../../../reference/vreplication/) workflow that enables you to move all or a subset of +tables between [keyspaces](../../../concepts/keyspace) without downtime. For example, after +[initially deploying Vitess](../../../get-started/local), your single `commerce` schema may grow so large that it needs +to be split into multiple [keyspaces](../../../concepts/keyspace) (often times referred to as vertical or functional sharding). + +All of the command options and parameters are listed in our [reference page for `MoveTables`](../../../reference/vreplication/movetables). + +As a stepping stone towards splitting a single table across multiple servers (sharding), it usually makes sense to first split from having a single monolithic keyspace (`commerce`) to having multiple keyspaces (`commerce` and `customer`). For example, in our hypothetical ecommerce system we may know that the `customer` and `corder` tables are closely related and both growing quickly. + +Let's start by simulating this situation by loading sample data: + +```bash +# On local and operator installs: +$ mysql < ../common/insert_commerce_data.sql +``` + +We can look at what we just inserted: + +```bash +# On local and operator installs: +$ mysql --table < ../common/select_commerce_data.sql +Using commerce +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 4 | dan@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +Product ++----------+-------------+-------+ +| sku | description | price | ++----------+-------------+-------+ +| SKU-1001 | Monitor | 100 | +| SKU-1002 | Keyboard | 30 | ++----------+-------------+-------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 4 | 4 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ +``` + +Notice that all of the tables are currently in the `commerce` schema/keyspace here. + +## Planning to Move Tables + +In this scenario, we are going to add the `customer` [keyspace](../../../concepts/keyspace) in addition to the `commerce` keyspace we already have. This new keyspace will be backed by its own set of mysqld instances. We will then move the `customer` and `corder` tables from the `commerce` keyspace to the newly created `customer` keyspace while the `product` table will remain in the `commerce` keyspace. This operation happens online, which means that it does not block either read or write operations to the tables, *except* for a very small window during the final cut-over. + +## Show our current tablets + +```bash +$ mysql -e "show vitess_tablets" ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| Cell | Keyspace | Shard | TabletType | State | Alias | Hostname | PrimaryTermStartTime | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| zone1 | commerce | 0 | PRIMARY | SERVING | zone1-0000000100 | localhost | 2023-01-04T17:59:37Z | +| zone1 | commerce | 0 | REPLICA | SERVING | zone1-0000000101 | localhost | | +| zone1 | commerce | 0 | RDONLY | SERVING | zone1-0000000102 | localhost | | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +``` + +As can be seen, we have 3 tablets running, with tablet ids 100, 101 and 102; which we use in the examples to form the tablet alias/names like `zone1-0000000100`, etc. + +## Create New Tablets + +The first step in our MoveTables operation is to deploy new tablets for our `customer` keyspace. By the convention used in our examples, we are going to use the tablet ids 200-202 as the `commerce` keyspace previously used `100-102`. Once the tablets have started, we will wait for the operator (k8s install) or `vtorc` (local install) to promote one of the new tablets to `PRIMARY` before proceeding: + +### Using Operator + +```bash +$ kubectl apply -f 201_customer_tablets.yaml +``` + +After a few minutes the pods should appear running: + +```bash +$ kubectl get pods +example-commerce-x-x-zone1-vtorc-c13ef6ff-5d658d78d8-dvmnn 1/1 Running 1 (4m39s ago) 65d +example-etcd-faf13de3-1 1/1 Running 1 (4m39s ago) 65d +example-etcd-faf13de3-2 1/1 Running 1 (4m39s ago) 65d +example-etcd-faf13de3-3 1/1 Running 1 (4m39s ago) 65d +example-vttablet-zone1-1250593518-17c58396 3/3 Running 1 (27s ago) 32s +example-vttablet-zone1-2469782763-bfadd780 3/3 Running 3 (4m39s ago) 65d +example-vttablet-zone1-2548885007-46a852d0 3/3 Running 3 (4m39s ago) 65d +example-vttablet-zone1-3778123133-6f4ed5fc 3/3 Running 1 (26s ago) 32s +example-zone1-vtadmin-c03d7eae-7dcd4d75c7-szbwv 2/2 Running 2 (4m39s ago) 65d +example-zone1-vtctld-1d4dcad0-6b9cd54f8f-jmdt9 1/1 Running 2 (4m39s ago) 65d +example-zone1-vtgate-bc6cde92-856d44984b-lqfvg 1/1 Running 2 (4m6s ago) 65d +vitess-operator-8df7cc66b-6vtk6 1/1 Running 0 55s +``` + +Again, the operator will promote one of the tablets to `PRIMARY` implicitly for you. + +Make sure that you restart the port-forward after launching the pods has completed: + +```bash +$ killall kubectl +./pf.sh & +``` + +### Using a Local Deployment + +```bash +$ ./201_customer_tablets.sh +``` + +## Show All Tablets + +```bash +$ mysql -e "show vitess_tablets" ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| Cell | Keyspace | Shard | TabletType | State | Alias | Hostname | PrimaryTermStartTime | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +| zone1 | commerce | 0 | PRIMARY | SERVING | zone1-0000000100 | localhost | 2023-01-04T17:59:37Z | +| zone1 | commerce | 0 | REPLICA | SERVING | zone1-0000000101 | localhost | | +| zone1 | commerce | 0 | RDONLY | SERVING | zone1-0000000102 | localhost | | +| zone1 | customer | 0 | PRIMARY | SERVING | zone1-0000000201 | localhost | 2023-01-04T18:00:22Z | +| zone1 | customer | 0 | REPLICA | SERVING | zone1-0000000200 | localhost | | +| zone1 | customer | 0 | RDONLY | SERVING | zone1-0000000202 | localhost | | ++-------+----------+-------+------------+---------+------------------+-----------+----------------------+ +``` + +{{< info >}} +The following change does not change actual query routing yet. We will later use the _SwitchTraffic_ action to perform that. +{{}} + +## Start the Move + +In this step we will create the `MoveTables` workflow, which copies the tables from the `commerce` keyspace into +`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 +``` + +A few things to note: + * In a real-world situation this process can take hours or even days to complete depending on the size of the table. + * The workflow name (`commerce2customer` in this case) is arbitrary, you can name it whatever you like. You will use this name for the other `MoveTables` actions like in the upcoming `SwitchTraffic` step. + +## Check Routing Rules (Optional) + +To see what happens under the covers, let's look at the [**routing rules**](../../../reference/features/schema-routing-rules/) that the `MoveTables` operation created. These are instructions used by a [`VTGate`](../../../concepts/vtgate) to determine which backend keyspace to send requests to for a given table — even when using a fully qualified table name such as `commerce.customer`: + +```json +$ vtctldclient GetRoutingRules +{ + "rules": [ + { + "fromTable": "customer.customer@rdonly", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "commerce.corder@rdonly", + "toTables": [ + "commerce.corder" + ] + }, + { + "fromTable": "customer", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "customer.customer@replica", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "corder@replica", + "toTables": [ + "commerce.corder" + ] + }, + { + "fromTable": "customer.corder", + "toTables": [ + "commerce.corder" + ] + }, + { + "fromTable": "commerce.corder@replica", + "toTables": [ + "commerce.corder" + ] + }, + { + "fromTable": "customer@rdonly", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "commerce.customer@replica", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "corder", + "toTables": [ + "commerce.corder" + ] + }, + { + "fromTable": "corder@rdonly", + "toTables": [ + "commerce.corder" + ] + }, + { + "fromTable": "customer.corder@rdonly", + "toTables": [ + "commerce.corder" + ] + }, + { + "fromTable": "customer@replica", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "customer.customer", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "commerce.customer@rdonly", + "toTables": [ + "commerce.customer" + ] + }, + { + "fromTable": "customer.corder@replica", + "toTables": [ + "commerce.corder" + ] + } + ] +} +``` + +The `MoveTables` operation has created [routing rules](../../../reference/features/schema-routing-rules/) to explicitly route +queries against the `customer` and `corder` tables — including the fully qualified `customer.customer` and `customer.corder` +names — to the respective tables in the `commerce` keyspace so that currently all requests go to the original keyspace. This +is done so that when `MoveTables` creates the new copy of the tables in the `customer` keyspace, there is no ambiguity about +where to route requests for the `customer` and `corder` tables. All requests for those tables will keep going to the original +instance of those tables in `commerce` keyspace. Any changes to the tables after the `MoveTables` is executed will +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: + +```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. +``` + +You can get detailed status and progress information using the +[`Workflow show`](../../../reference/vreplication/workflow/) command: +```json +$ vtctlclient Workflow customer.commerce2customer show +{ + "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": "" +} +``` + +## Validate Correctness (Optional) + +We can use [`VDiff`](../../../reference/vreplication/vdiff/) to perform a logical diff between the sources and target +to confirm that they are fully in sync: + +```bash +$ vtctlclient VDiff -- --v2 customer.commerce2customer create +{ + "UUID": "d050262e-8c5f-11ed-ac72-920702940ee0" +} + +$ vtctlclient VDiff -- --v2 --format=json --verbose customer.commerce2customer show last +{ + "Workflow": "commerce2customer", + "Keyspace": "customer", + "State": "completed", + "UUID": "d050262e-8c5f-11ed-ac72-920702940ee0", + "RowsCompared": 10, + "HasMismatch": false, + "Shards": "0", + "StartedAt": "2023-01-04 18:44:26", + "CompletedAt": "2023-01-04 18:44:26", + "TableSummary": { + "corder": { + "TableName": "corder", + "State": "completed", + "RowsCompared": 5, + "MatchingRows": 5, + "MismatchedRows": 0, + "ExtraRowsSource": 0, + "ExtraRowsTarget": 0 + }, + "customer": { + "TableName": "customer", + "State": "completed", + "RowsCompared": 5, + "MatchingRows": 5, + "MismatchedRows": 0, + "ExtraRowsSource": 0, + "ExtraRowsTarget": 0 + } + }, + "Reports": { + "corder": { + "0": { + "TableName": "corder", + "ProcessedRows": 5, + "MatchingRows": 5, + "MismatchedRows": 0, + "ExtraRowsSource": 0, + "ExtraRowsTarget": 0 + } + }, + "customer": { + "0": { + "TableName": "customer", + "ProcessedRows": 5, + "MatchingRows": 5, + "MismatchedRows": 0, + "ExtraRowsSource": 0, + "ExtraRowsTarget": 0 + } + } + } +} +``` + +{{< info >}} +This can take a long time to complete on very large tables. +{{}} + +## Switching Traffic + +Once the `MoveTables` operation is complete ([in the "running" or replicating phase](../../../../design-docs/vreplication/life-of-a-stream/)), the first step in making the changes live is to _switch_ all query serving +traffic from the old `commerce` keyspace to the `customer` keyspace for the tables we moved. Queries against the other +tables will continue to route to the `commerce` keyspace. + +```bash +$ vtctlclient MoveTables -- SwitchTraffic customer.commerce2customer + +SwitchTraffic was successful for workflow customer.commerce2customer +Start State: Reads Not Switched. Writes Not Switched +Current State: All Reads Switched. Writes Switched +``` + +{{< info >}} +While we have switched all traffic in this example, you can also switch non-primary reads and writes separately by +specifying the [`--tablet_types`](../../../reference/vreplication/movetables/#--tablet_types) parameter to +`SwitchTraffic`. +{{}} + +## Check the Routing Rules (Optional) + +If we now look at the [routing rules](../../../reference/features/schema-routing-rules/) after the `SwitchTraffic` +step, we will see that all queries against the `customer` and `corder` tables will get routed to the `customer` keyspace: + +```json +$ vtctldclient GetRoutingRules +{ + "rules": [ + { + "from_table": "commerce.corder@rdonly", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "corder@rdonly", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "customer.corder@replica", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "commerce.corder@replica", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "customer.corder@rdonly", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "customer@replica", + "to_tables": [ + "customer.customer" + ] + }, + { + "from_table": "customer.customer@replica", + "to_tables": [ + "customer.customer" + ] + }, + { + "from_table": "corder@replica", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "commerce.customer@rdonly", + "to_tables": [ + "customer.customer" + ] + }, + { + "from_table": "customer@rdonly", + "to_tables": [ + "customer.customer" + ] + }, + { + "from_table": "customer.customer@rdonly", + "to_tables": [ + "customer.customer" + ] + }, + { + "from_table": "commerce.customer@replica", + "to_tables": [ + "customer.customer" + ] + }, + { + "from_table": "corder", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "commerce.corder", + "to_tables": [ + "customer.corder" + ] + }, + { + "from_table": "customer", + "to_tables": [ + "customer.customer" + ] + }, + { + "from_table": "commerce.customer", + "to_tables": [ + "customer.customer" + ] + } + ] +} +``` + +## 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) +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 +and called `commerce2customer`, the reverse workflow is in the `commerce` keyspace and called +`commerce2customer_reverse`. We can see the details of this auto-created workflow using the +[`Workflow show`](../../../reference/vreplication/workflow/) command: + +```json +$ vtctlclient Workflow commerce.commerce2customer_reverse show +{ + "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": "" +} +``` + +## Finalize and Cleanup + +The final step is to complete the migration using the [`Complete`](../../../reference/vreplication/movetables/#complete) action. +This will (by default) get rid of the [routing rules](../../../reference/features/schema-routing-rules/) that were created and +`DROP` the original tables in the source keyspace (`commerce`). Along with freeing up space on the original tablets, this is an +important step to eliminate potential future confusion. If you have a misconfiguration down the line and accidentally route queries +for the `customer` and `corder` tables to the `commerce` keyspace, it is much better to return a *"table not found"* +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 +``` + +{{< info >}} +This command will return an error if you have not already switched all traffic. +{{}} + +After this step is complete, you should see an error if you try to query the moved tables in the original `commerce` +keyspace: + +```bash +# Expected to fail! +$ mysql < ../common/select_commerce_data.sql +Using commerce +Customer +ERROR 1146 (42S02) at line 4: target: commerce.0.primary: vttablet: rpc error: code = NotFound desc = Table 'vt_commerce.customer' doesn't exist (errno 1146) (sqlstate 42S02) (CallerID: userData1): Sql: "select * from customer", BindVars: {} + +# Expected to be empty +$ vtctldclient GetRoutingRules +{ + "rules": [] +} + +# Workflow is gone +$ vtctlclient Workflow customer listall +No workflows found in keyspace customer + +# Reverse workflow is also gone +$ vtctlclient Workflow commerce listall +No workflows found in keyspace commerce +``` + +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. + +## Next Steps + +Congratulations! You've successfully moved tables between into Vitess or between keyspaces. The next step to try out is +sharding one of your keyspaces using [Resharding](../../configuration-advanced/resharding). diff --git a/content/en/docs/19.0/user-guides/migration/troubleshooting.md b/content/en/docs/19.0/user-guides/migration/troubleshooting.md new file mode 100644 index 000000000..48523e07d --- /dev/null +++ b/content/en/docs/19.0/user-guides/migration/troubleshooting.md @@ -0,0 +1,252 @@ +--- +title: Troubleshooting +weight: 4 +--- + +## Overview + +Here we will cover some common issues seen during a migration — how to avoid them, how to detect them, and how to address them. + +{{< info >}} +This guide follows on from the [Get Started](../../../get-started/) guides. Please make sure that you have a +[Kubernetes Operator](../../../get-started/operator) or [local](../../../get-started/local) installation ready. +Make sure you have run the "101" and "201" steps of the examples, for example the "101" step is +`101_initial_cluster.sh` in the [local](../../../get-started/local) example. The commands in this guide also assume +you have setup the shell aliases from the example, e.g. `env.sh` in the [local](../../../get-started/local) example. +{{< /info >}} + + +## General and Precautionary Info + +### Execute a Dry Run + +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 +be particularly helpful during the final cutover stage. + +### DDL Handling + +If you expect DDL to be executed on the source table(s) while the workflow runs and you want those DDL statements +to be replicated to the target keyspace then you will need to use one of the `EXEC*` options for the workflow's +[`on-ddl`](../../../reference/vreplication/vreplication/#handle-ddl) flag. Please see the +[`on-ddl` flag documentation](../../../reference/vreplication/vreplication/#handle-ddl) for additional details and +related considerations. + +## Running a Diff + +In most cases you should run a [`VDiff`](../../../reference/vreplication/vdiff/) before switching traffic to ensure +that nothing unexpected happened which caused the data to diverge during the migration. + +## Performance Notes + +- VReplication workflows (including [`VDiff`](../../../reference/vreplication/vdiff/)) can have a major impact on the +tablet so it's recommended to use non-PRIMARY tablets whenever possible to limit any impact on production traffic + - You can see the key related tablet flags and when/why you may want to set them in the [VReplication tablet flag docs](../../../reference/vreplication/flags/) + - You can further control any impact on the source and target tablets using [the tablet throttler](../../../reference/features/tablet-throttler/) +- VReplication workflows can generate a lot of network traffic + - You should strive to keep the source and target tablets in the same [cell](../../../concepts/cell) whenever possible to limit performance and cost impacts + +## 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 [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 + +### Save Routing Rules + +The `Create`, `SwitchTraffic`/`ReverseTraffic`, and `Cancel`/`Complete` actions modify the +[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 +``` + + +## Specific Errors and Issues + +### 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` +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 + +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 +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 +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. +``` + +### 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'). + +# 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]. +``` + +This can be caused by a DDL executed on the source table as by default — controlled by the +[`on-ddl` flag value](../../../reference/vreplication/vreplication/#handle-ddl) — DDL is ignored in the stream. + +#### 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 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. + + +$ vtctlclient MoveTables -- Progress customer.commerce2customer + +The following vreplication streams exist for workflow customer.commerce2customer: + +id=2 on 0/zone1-0000000201: Status: Running. VStream Lag: 0s. +``` + +### 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 + +Lock keyspace commerce +Switch reads for tables [corder,customer] to keyspace customer for tablet types [RDONLY,REPLICA] +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 +Create journal entries on source databases +Enable writes on keyspace customer 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 +Unlock keyspace customer +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 +`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} + done + +# Ensure that these changes are in place everywhere +$ vtctldclient RefreshStateByShard customer/0 +``` + +### Completion and Cleanup Failures + +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 + +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 +Unlock keyspace customer +Unlock keyspace commerce +``` \ No newline at end of file diff --git a/content/en/docs/19.0/user-guides/operating-vitess/_index.md b/content/en/docs/19.0/user-guides/operating-vitess/_index.md new file mode 100644 index 000000000..52b1bb48b --- /dev/null +++ b/content/en/docs/19.0/user-guides/operating-vitess/_index.md @@ -0,0 +1,6 @@ +--- +title: Operational +description: User guides covering operational aspects of Vitess +weight: 5 +skip_sections: true +--- diff --git a/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/_index.md b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/_index.md new file mode 100644 index 000000000..4305c3607 --- /dev/null +++ b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/_index.md @@ -0,0 +1,5 @@ +--- +title: Backup and Restore +description: User guides covering how to backup and restore in Vitess +weight: 1 +--- diff --git a/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md new file mode 100644 index 000000000..fefc571b4 --- /dev/null +++ b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/bootstrap-and-restore.md @@ -0,0 +1,99 @@ +--- +title: Bootstrap and Restore +weight: 3 +aliases: ['/docs/user-guides/backup-and-restore/'] +--- + +Restores can be done automatically by way of seeding/bootstrapping new tablets, or they can be invoked manually on a tablet to restore a full backup or do a point-in-time recovery. +## Auto restoring a backup on startup + +When a tablet starts, Vitess checks the value of the `--restore_from_backup` command-line flag to determine whether to restore a backup to that tablet. Restores will always be done with whichever engine was used to create the backup. + +* If the flag is present, Vitess tries to restore the most recent backup from the [BackupStorage](../overview/#backup-storage-services) system when starting the tablet or if the `--restore_from_backup_ts` flag (Vitess 12.0+) is also set then using the latest backup taken at or before this timestamp instead. Example: '2021-04-29.133050' +* If the flag is absent, Vitess does not try to restore a backup to the tablet. This is the equivalent of starting a new tablet in a new shard. + +This flag is generally enabled all of the time for all of the tablets in a shard. By default, if Vitess cannot find a backup in the Backup Storage system, the tablet will start up empty. This behavior allows you to bootstrap a new shard before any backups exist. + +If the `--wait_for_backup_interval` flag is set to a value greater than zero, the tablet will instead keep checking for a backup to appear at that interval. This can be used to ensure tablets launched concurrently while an initial backup is being seeded for the shard (e.g. uploaded from cold storage or created by another tablet) will wait until the proper time and then pull the new backup when it's ready. + +``` sh +vttablet ... --backup_storage_implementation=file \ + --file_backup_storage_root=/nfs/XXX \ + --restore_from_backup +``` + +## Bootstrapping a new tablet + +Bootstrapping a new tablet is almost identical to restoring an existing tablet. The only thing you need to be cautious about is that the tablet specifies its keyspace, shard and tablet type when it registers itself in the topology. Specifically, make sure that the following additional vttablet parameters are set: + +``` sh + --init_keyspace + --init_shard + --init_tablet_type replica|rdonly +``` + +The bootstrapped tablet will restore the data from the backup and then apply changes, which occurred after the backup, by restarting replication. + +## Manual restore + +A manual restore is done on a specific tablet. The tablet's MySQL server is shut down and its data is wiped out. + +### Restore a full backup + +To restore the tablet from the most recent full backup, run: + +```shell +vtctldclient --server=: RestoreFromBackup +``` + +Example: + +```shell +vtctldclient --server localhost:15999 --alsologtostderr RestoreFromBackup zone1-0000000101 +``` + +If successful, the tablet's MySQL server rejoins the shard's replication stream, to eventually captch up and be able to serve traffic. + +### Restore to a point-in-time + +Vitess supports restoring to a _timestamp_ or to a specific _position_. Either way, this restore method assumes backups have been taken that cover the specified position. The restore process will first determine a restore path: a sequence of backups, starting with a full backup followed by zero or more incremental backups, that when combined, include the specified timestamp or position. See more on [Restore Types](../overview/#restore-types) and on [Taking Incremental Backup](../creating-a-backup/#create-an-incremental-backup-with-vtctl). + +#### Restore to timestamp + +Starting with `v18`, it is possible to restore to a given timestamp. The restore process will apply all events up to, and excluding, the given timestamp, at 1 second granularity. That is, the restore will bring the database to a point in time which is _about_ 1 second before the specified timestamp. Example: + +```shell +vtctldclient RestoreFromBackup --restore-to-timestamp "2023-06-15T09:49:50Z" zone1-0000000100 +``` + +The timestamp must be in `RFC3339` format. + +#### Restore to a position + +It is possible to restore onto a precise GTID position. Vitess will restore up to, and including, the exact requested position. This gives you the utmost granularity into the state of the restored database. + +```shell +vtctldclient RestoreFromBackup --restore-to-pos +``` + +Example: + +```shell +vtctldclient RestoreFromBackup --restore-to-pos "MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-60" zone1-0000000102 +``` + +#### Dry run + +It is possible to verify whether a restore-to-timestamp or restore-to-pos is possible without actually performing the restore. Run: + + +```shell +vtctldclient RestoreFromBackup --dry-run --restore-to-timestamp "2023-06-15T09:49:50Z" zone1-0000000100 +``` + +or +```shell +vtctldclient RestoreFromBackup --dry-run --restore-to-pos "MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-60" zone1-0000000102 +``` + +A dry run restore looks at existing backups and sees whether there is a path that restores up to given timestamp or pos, but then quits and does not interrupt any tablet's execution and without changing the tablet's type. If there's no valid path to restore, the process exits with error. \ No newline at end of file diff --git a/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md new file mode 100644 index 000000000..5eda514e3 --- /dev/null +++ b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup.md @@ -0,0 +1,133 @@ +--- +title: Creating a Backup +weight: 2 +aliases: ['/docs/user-guides/backup-and-restore/'] +--- + +## Choosing the backup type + +As described in [Backup types](../overview/#backup-types), you choose to run a full Backup (the default) or an incremental Backup. + +Full backups will use the backup engine chosen in the tablet's [configuration](#configuration). Incremental backups will always copy MySQL's binary logs, irrespective of the configured backup engine. + +## Using xtrabackup + +The default backup implementation is `builtin`, however we strongly recommend using the `xtrabackup` engine as it is more robust and allows for non-blocking backups. Restores will always be done with whichever engine was used to create the backup. + +### Prerequisites + +A compatible version of [xtrabackup](https://www.percona.com/doc/percona-xtrabackup/latest/index.html) and [xbstream](https://docs.percona.com/percona-xtrabackup/8.0/xtrabackup_bin/backup.streaming.html), if needed, must be present in your `$PATH` prior to running the `Backup[Shard]` command. + +### Supported Versions + +* [MySQL 5.7](https://www.percona.com/doc/percona-xtrabackup/2.4/index.html#installation) +* [MySQL 8.0](https://www.percona.com/doc/percona-xtrabackup/8.0/index.html#installation) + +### Configuration + +To use `xtrabackup` with Vtbackup, VTTablet or Vtctld, the following flags must be set. + +__Required flags:__ + +* `--backup_engine_implementation=xtrabackup` +* `--xtrabackup_user string` + * The user that xtrabackup will use to connect to the database server. This user must have the [necessary privileges](https://www.percona.com/doc/percona-xtrabackup/2.4/using_xtrabackup/privileges.html#permissions-and-privileges-needed). + * This user will need to be authorized to connect to mysql locally without a password using [auth_socket](https://dev.mysql.com/doc/refman/5.7/en/socket-pluggable-authentication.html). + +Additionally required for MySQL 8.0: + +* `--xtrabackup_stream_mode=xbstream` + + + +### Common Errors and Resolutions + +__No xtrabackup User passed to vttablet:__ + +``` +E0310 08:15:45.336083 197442 main.go:72] remote error: rpc error: code = Unknown desc = TabletManager.Backup on zone1-0000000102 error: xtrabackupUser must be specified.: xtrabackupUser must be specified +``` + +Fix: Set the vtctld and vttablet flag `--xtrabackup_user` + +__xtrabackup binary not found in $PATH:__ + +``` +E0310 08:22:22.260044 200147 main.go:72] remote error: rpc error: code = Unknown desc = TabletManager.Backup on zone1-0000000102 error: unable to start backup: exec: "xtrabackup": executable file not found in $PATH: unable to start backup: exec: "xtrabackup": executable file not found in $PATH +``` + +Fixes: + + * Ensure the xtrabackup binary is in the $PATH for the $USER running vttablet + * Alternatively, set --xtrabackup_root_path on vttablet provide path to xtrabackup/xbstream binaries via vtctld and vttablet flags + +__Tar format no longer supported in 8.0:__ + +``` +I0310 12:34:47.900363 211809 backup.go:163] I0310 20:34:47.900004 xtrabackupengine.go:310] xtrabackup stderr: Invalid --stream argument: tar +Streaming in tar format is no longer supported in 8.0; use xbstream instead +``` + +Fix: Set the `--xtrabackup_stream_mode` flag to to xbstream on vttablets and vtctlds + +__Unsupported mysql server version:__ + +``` +I0310 12:49:32.279729 215835 backup.go:163] I0310 20:49:32.279435 xtrabackupengine.go:310] xtrabackup stderr: Error: Unsupported server version 8.0.23-0ubuntu0.20.04.1. +I0310 12:49:32.279773 215835 backup.go:163] I0310 20:49:32.279485 xtrabackupengine.go:310] xtrabackup stderr: Please upgrade PXB, if a new version is available. To continue with risk, use the option --no-server-version-check. +``` + +To continue with risk: Set `--xtrabackup_backup_flags=--no-server-version-check`. Note this occurs when your MySQL server version is technically unsupported by `xtrabackup`. + +## Create a full backup with vtctl + +__Run the following vtctl command to create a backup:__ + +```sh +vtctldclient --server=: Backup [--upgrade-safe=false] +``` + +If the engine is `builtin`, replication will be stopped prior to shutting down mysqld for the backup. + +If the engine is `xtrabackup`, the tablet can continue to serve traffic while the backup is running. + +__Run the following vtctl command to backup a specific shard:__ + +``` sh +vtctldclient --server=: BackupShard [--allow_primary=false] [--upgrade-safe=false] +``` + +## Create an incremental backup with vtctl + +An incremental backup requires additional information: the point from which to start the backup. An incremental backup is taken by supplying `--incremental-from-pos` to the `Backup` or `BackupShard` command. The argument may either indicate a valid position, or the value `auto`. Examples: + +```sh +vtctldclient Backup --incremental-from-pos="MySQL56/0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-53" zone1-0000000102 + +vtctldclient Backup --incremental-from-pos="0d7aaca6-1666-11ee-aeaf-0a43f95f28a3:1-53" zone1-0000000102 + +vtctldclient Backup --incremental-from-pos="auto" zone1-0000000102 + +vtctldclient BackupShard --incremental-from-pos=auto commerce/0 +``` + +When indicating a position, you may choose to use or to omit the `MySQL56/` prefix (which you can find in the backup manifest's Position). + +When `--incremental-from-pos="auto"`, Vitess chooses the position of the last successful backup as the starting point for the incremental backup. This is a convenient way to ensure a sequence of contiguous incremental backups. + +An incremental backup backs up one or more MySQL binary log files. These binary log files may begin with the requested position, or with an earlier position. They will necessarily include the requested position. When the incremental backup begins, Vitess rotates the MySQL binary logs on the tablet, so that it does not back up an active log file. + +An incremental backup fails in these scenarios: + +- It is unable to find binary log files that covers the requested position. This can happen if the binary logs are purged earlier than the incremental backup was taken. It essentially means there's a gap in the changelog events. **Note** that while on one tablet the binary logs may be missing, another tablet may still have binary logs that cover the requested position. +- There is no change to the database since the requested position, i.e. the GTID position has not changed since. + +## Backing up Topology Server + +The Topology Server stores metadata (and not tablet data). It is recommended to create a backup using the method described by the underlying plugin: + +* [etcd](https://etcd.io/docs/v3.4.0/op-guide/recovery/) +* [ZooKeeper](http://zookeeper.apache.org/doc/r3.6.0/zookeeperAdmin.html#sc_dataFileManagement) +* [Consul](https://www.consul.io/docs/commands/snapshot.html) diff --git a/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/managing-backups.md b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/managing-backups.md new file mode 100644 index 000000000..0b4f8182f --- /dev/null +++ b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/managing-backups.md @@ -0,0 +1,44 @@ +--- +title: Managing Backups +weight: 4 +aliases: ['/docs/user-guides/backup-and-restore/'] +--- + +**vtctldclient** provides two commands for managing backups: + +* [GetBackups](https://vitess.io/docs/reference/programs/vtctldclient/vtctldclient_getbackups/) displays the existing backups for a keyspace/shard in chronological order. + + ``` sh + vtctldclient --server=: GetBackups + ``` + +* [RemoveBackup](https://vitess.io/docs/reference/programs/vtctldclient/vtctldclient_removebackup/) deletes a specified backup for a keyspace/shard. + + ``` sh + vtctldclient --server=: RemoveBackup + ``` + +You can also confirm your backup finished by viewing the files in your configured `--_backup_storage_root` location. You will still need to test and verify these backups for completeness. Note that backups are stored by keyspace and shard under `--_backup_storage_root`. For example, when using `--file_backup_storage_root=/vt/vtdataroot/backups`: + +```sh +/vt/vtdataroot/backups/commerce/0/2021-03-10.205419.zone1-0000000102: +backup.xbstream.gz MANIFEST +``` + +Each backup contains a manifest file with general information about the backup: + +```sh +MySQL 8.0 xbstream Manifest +{ + "BackupMethod": "xtrabackup", + "Position": "MySQL56/c022ad67-81fc-11eb-aa0e-1c1bb572885f:1-50", + "BackupTime": "2021-03-11T00:01:37Z", + "FinishedTime": "2021-03-11T00:01:42Z", + "FileName": "backup.xbstream.gz", + "ExtraCommandLineParams": "--no-server-version-check", + "StreamMode": "xbstream", + "NumStripes": 0, + "StripeBlockSize": 102400, + "SkipCompress": false +} +``` diff --git a/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/overview.md b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/overview.md new file mode 100644 index 000000000..d7ac333d1 --- /dev/null +++ b/content/en/docs/19.0/user-guides/operating-vitess/backup-and-restore/overview.md @@ -0,0 +1,332 @@ +--- +title: Overview +weight: 1 +aliases: ['/docs/user-guides/backup-and-restore/'] +--- + +Backup and Restore are integrated features provided by tablets managed by Vitess. As well as using _backups_ for data integrity, Vitess will also create and restore backups for provisioning new tablets in an existing shard. + +## Concepts + +Vitess supports pluggable interfaces for both [Backup Storage Services](https://github.com/vitessio/vitess/blob/main/go/vt/mysqlctl/backupstorage/interface.go) and [Backup Engines](https://github.com/vitessio/vitess/blob/main/go/vt/mysqlctl/backupengine.go). + +### Backup Storage Services + +Currently, Vitess has plugins for: + +* File (using a path on shared storage, e.g. an NFS mount) +* Google Cloud Storage +* Amazon S3 +* Ceph + +### Backup Engines + +The engine is the techology used for generating the backup. Currently Vitess has plugins for: + +* Builtin: Shutdown an instance and copy all the database files (default) +* XtraBackup: An online backup using Percona's [XtraBackup](https://www.percona.com/software/mysql-database/percona-xtrabackup) + +### Backup types + +Vitess supports full backups as well as incremental backups, and their respective counterparts full restores and point-in-time restores. + +* A full backup contains the entire data in the database. The backup represents a consistent state of the data, i.e. it is a snapshot of the data at some point in time. +* An incremental backup contains a changelog, or a transition of data from one state to another. Vitess implements incremental backups by making a copy of MySQL binary logs. + +Generally speaking and on most workloads, the cost of a full backup is higher, and the cost of incremental backups is lower. The time it takes to create a full backup is significant, and it is therefore impractical to take full backups in very small intervals. Moreover, a full backup consumes the disk space needed for the entire dataset. Incremental backups, on the other hand, are quick to run, and have very little impact, if any, to the running servers. They only contain the changes in between two points in time, and on most workloads are more compact. + +Full and incremental backups are expected to be interleaved. For example: one would create a full backup once per day, and incremental backups once per hour. + +Full backups are simply states of the database. Incremental backups, however, need to start with some point and end with some point. The common practice is for an incremental backup to continue from the point of the last good backup, which can be a full or incremental backup. An inremental backup in Vitess ends at the point in time of execution. + +The identity of the tablet on which a full backup or an incremental backup is taken is immaterial. It is possible to take a full backup on one tablet and incremental backups on another. It is possible to take full backups on two different tablets. It is also possible to take incremental backups, independently, on two different tablets, even though the contents of those incremental backups overlaps. Vitess uses MySQL GTID sets to determine positioning and prune duplicates. + +### Restores + +Restores are the counterparts of backups. A restore uses the engine utilized to create a backup. One may run a restore from a full backup, or a point-in-time restore (PITR) based on additional incremental backups. + +A Vitess restore operates on a tablet. The restore process completely wipes out the data in the tablet's MySQL server and repopulates the server with the backup(s) data. The MySQL server is shutdown during the process. As a safety mechanism, Vitess by default prevents a restore onto a `PRIMARY` tablet. Any non-`PRIMARY` tablet is otherwise eligible to restore. + +### Restore Types + +Vitess supports full restores and incremental (AKA point-in-time) restores. The two serve different purposes. + +* A full restore loads the dataset from a full backup onto a non-`PRIMARY` tablet. Once the data is loaded, the restore process starts the MySQL service and makes it join the replication stream. It is expected that a freshly restored server will lag behind the shard's `PRIMARY` for a period of time. + The full restore flow is useful for seeding new replica tablets. It may also be used to fix replicas that have been corrupted. +* An incremental, or a point-in-time restore, restores a tablet/MySQL up to a specific position or time. This is done by first loading a full backup dataset, followed by applying the changelog captured in zero or more incremental backups. Once that is complete, the tablet type is set to `DRAINED` and the tablet does _not_ join the replication stream. + The common purpose of point-in-time restore is to recover data from an accidental write/deletion. If the database administrator knows at about what time the accidental write took place, they can restore a replica tablet to a point in time shortly before the accidental write. Since the server does not join the replication stream, its data then remains static, and the administrator may review or copy the data as they please. Finally, it is then possible to change the tablet type back to `REPLICA` and have it join the shard's replication. + +## Vtbackup, VTTablet and Vtctld + +Vtbackup, VTTablet, and Vtctld may all participate in backups and restores. + + * Vtbackup is a standalone program that restores the last backup into an empty mysqld installation, replicates new changes into that installation, and takes a new backup from that installation. + * VTTablet can be configured to restore from a backup, or to take a new backup. + * Vtctld can be instructed to take backups with commands like `Backup` and `BackupShard`. + +### Configuration + +Before backing up or restoring a tablet, you need to ensure that the tablet is aware of the Backup Storage system and Backup Engine that you are using. + +To do so, use command-line flags to configure vtbackup, vttablet, or vtctld programs that have access to the location where you are storing backups. + +__Common flags:__ + +All three programs can be made aware of Backup Engine and Backup Storage using these common flags. + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDefinition
    backup_storage_implementationSpecifies the implementation of the Backup Storage interface to + use.

    + Current plugin options available are: +
      +
    • file: Using shared storage (e.g. NFS).
      • +
    • gcs: Google Cloud Storage.
      • +
    • s3: Amazon S3.
      • +
    • ceph: Ceph Object Gateway S3 API.
      • +
    +
    backup_engine_implementationSpecifies the implementation of the Backup Engine to + use.

    + Current options available are: +
      +
    • builtin: Copy all the database files into specified storage. This is the default.
      • +
    • xtrabackup: Percona XtraBackup.
      • +
    +
    backup_storage_compressThis flag controls if the backups are compressed by the Vitess code. + By default it is set to true. Use + --backup_storage_compress=false to disable.
    +
    backup_storage_block_sizeIf --backup_storage_compress is true, backup_storage_block_size sets the block size in bytes to use while compressing (default is 250000). +
    backup_storage_number_blocksIf --backup_storage_compress is true, backup_storage_number_blocks sets the number of blocks that can be processed, in parallel, before the writer blocks, during compression. It should be equal to the number of CPUs available for compression. (default 2) +
    compression-levelSelect what is the compression level (from `1..9`) to be used with the builtin compressors. + It doesn't have any effect if you are using an external compressor. Defaults to + 1 (fastest compression). +
    compression-engine-name + This indicates which compression engine to use. The default value is pargzip. + If using an external compressor (see below), this should be a compatible compression engine as the + value will be saved to the MANIFEST when creating the backup and can be used to decompress it. +
    external-compressor + Instead of compressing inside the vttablet process, use the external command to + compress the input. The compressed stream needs to be written to STDOUT.

    + An example command to compress with an external compressor using the fastest mode and lowest CPU priority:
    + --external-compressor "nice -n 19 pigz -1 -c"

    + If the backup is supported by one of the builtin engines, make sure to use --compression-engine-name + so it can be restored without requiring --external-decompressor to be defined. +
    external-compressor-extension + Using the --external-compressor-extension flag will set the correct extension when + writing the file. Only used for the xtrabackupengine.

    + Example: --external-compressor-extension ".gz" +
    external-decompressor + Use an external decompressor to process the backups. This overrides the builtin + decompressor which would be automatically select the best engine based on the MANIFEST information. + The decompressed stream needs to be written to STDOUT.

    + An example of how to use an external decompressor:
    + --external-decompressor "pigz -d -c" +
    file_backup_storage_rootFor the file plugin, this identifies the root directory + for backups. This path must exist on shared storage to provide a global backup view for all vtctlds and vttablets. +
    gcs_backup_storage_bucketFor the gcs plugin, this identifies the + bucket + to use.
    s3_backup_aws_regionFor the s3 plugin, this identifies the AWS region.
    s3_backup_storage_bucketFor the s3 plugin, this identifies the AWS S3 + bucket.
    ceph_backup_storage_configFor the ceph plugin, this identifies the path to a text + file with a JSON object as configuration. The JSON object requires the + following keys: accessKey, secretKey, + endPoint and useSSL. Bucket name is computed + from keyspace name and shard name is separated for different + keyspaces / shards.
    restart_before_backupIf set, perform a clean MySQL shutdown and startup cycle. Note this is not + executing any `FLUSH` statements. This enables users to work around xtrabackup + DDL issues.
    xbstream_restore_flagsThe flags to pass to the xbstream command during restore. These should be space separated and will be added to the end of the command. These need to match the ones used for backup e.g. --compress / --decompress, --encrypt / --decrypt
    xtrabackup_root_pathFor the xtrabackup backup engine, directory location of the xtrabackup executable, e.g., `/usr/bin`
    xtrabackup_backup_flagsFor the xtrabackup backup engine, flags to pass to the backup command. These should be space separated and will be added to the end of the command.
    xtrabackup_stream_modeFor the xtrabackup backup engine, which mode to use if streaming, valid values are tar and xbstream. Defaults to tar.
    xtrabackup_userFor the xtrabackup backup engine, required user that xtrabackup will use to connect to the database server. This user must have all necessary privileges. For details, please refer to xtrabackup documentation.
    xtrabackup_stripesFor the xtrabackup backup engine, if greater than 0, use data striping across this many destination files to parallelize data transfer and decompression.
    xtrabackup_stripe_block_sizeFor the xtrabackup backup engine, size in bytes of each block that gets sent to a given stripe before rotating to the next stripe. Defaults to 102400.
    xtrabackup_prepare_flagsFlags to pass to the prepare command. These should be space separated and will be added to the end of the command.
    + +__Restore flags:__ + +Only VTTablet can be configured to restore from a previous backup. The flags below only apply to VTTablet. + + + + + + + + + + + + + + + + + + +
    NameDefinition
    restore_from_backupIndicates that, when started with an empty MySQL instance, the + tablet should restore the most recent backup from the specified + storage plugin. This flag only applies to VTTablet.
    restore_from_backup_tsIf set, restore the latest backup taken at or before this timestamp + rather than using the most recent one. Example: ‘2021-04-29.133050’. + (Vitess 12.0+)
    + +### Authentication + +Note that for the Google Cloud Storage plugin, we currently only support +[Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). This means that access to Google Cloud Storage (GCS) is automatically granted by virtue of the fact that you're already running within Google Compute Engine (GCE) or Google Kubernetes Engine (GKE). + +For this to work, the GCE instances must have been created with the [scope](https://cloud.google.com/compute/docs/authentication#using) that grants read-write access to GCS. When using GKE, you can do this for all the instances it creates by adding `--scopes storage-rw` to the `gcloud container clusters create` command. + +### Backup Frequency + +We recommend to take backups regularly -- e.g. you should set up a cron job for it. + +To determine the proper frequency for creating backups, consider the amount of time that you keep replication logs (see the [binlog_expire_logs](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_expire_logs_seconds) variables) and allow enough time to investigate and fix problems in the event that a backup operation fails. + +For example, suppose you typically keep four days of replication logs and you create daily backups. In that case, even if a backup fails, you have at least a couple of days from the time of the failure to investigate and fix the problem. + +### Concurrency + +The backup and restore processes simultaneously copy and either compress or decompress multiple files to increase throughput. You can control the concurrency using command-line flags: + +* The vtctl [Backup](https://vitess.io/docs/reference/programs/vtctl/tablets/#backup) command uses the `--concurrency` flag. +* vttablet uses the `--restore_concurrency` flag. + +If the network link is fast enough, the concurrency matches the CPU usage of the process during the backup or restore process. + +### Backup Compression + +By default, `vttablet` backups are compressed using `pargzip` that generates `gzip` compatible files. +You can select other builtin engines that are supported, or choose to use an external process to do the +compression/decompression for you. There are some advantages of doing this, like being able to set the +scheduling priority or even to choose dedicated CPU cores to do the compression, things that are not possible when running inside the `vttablet` process. + +The built-in supported engines are: + +__Compression:__ +- `pargzip` (default) +- `pgzip` +- `lz4` +- `zstd` + +__Decompression:__ +- `pgzip` +- `lz4` +- `zstd` + +To change which compression engine to use, you can use the `--compression-engine-name` flag. The compression +engine will also be saved to the backup manifest, which is read during the decompression process to select +the right engine to decompress (so even if it gets changed, the `vttablet` will still be able to restore +previous backups). + +If you want to use an external compressor/decompressor, you can do this by setting: +- `--external-compressor` with the command that will actually compress the stream; +- `--external-compressor-extension` (only if using xtrabackupengine): this will let you use the extension of the file saved +- `--compression-engine-name` with the compatible engine that can decompress it. Use `external` if you are using an external engine not included in the above supported list. This value will be saved to the backup +MANIFEST; If it is not added (or engine is `external`), backups won't be able to restore unless you pass the parameter below: +- `--external-decompressor` with the command used to decompress the files; + +The `vttablet` process will launch the external process and pass the input stream via STDIN and expects +the process will write the compressed/decompressed stream to STDOUT. + +If you are using an external compressor and want to move to a builtin engine: +- If the engine is supported according to the list above, you just need to make sure your `--compression-engine-name` is correct and you can remove +the `--external-compressor` parameter +- If you want to move away from an unsupported engine to a builtin one, then you have to: + - First change the `--compression-engine-name` to a supported one and remove the `--external-compressor` + - Once the first backup is completed, you can then remove `--external-decompressor` + - After this all new backups will be done using the new engine. Restoring an older backup will still require the `--external-decompressor` flag to be provided diff --git a/content/en/docs/19.0/user-guides/operating-vitess/upgrading-vitess.md b/content/en/docs/19.0/user-guides/operating-vitess/upgrading-vitess.md new file mode 100644 index 000000000..7533be294 --- /dev/null +++ b/content/en/docs/19.0/user-guides/operating-vitess/upgrading-vitess.md @@ -0,0 +1,48 @@ +--- +title: Upgrading Vitess +weight: 1 +aliases: ['/docs/user-guides/upgrading/', '/docs/user-guides/upgrading-vitess/'] +--- + +This document highlights things to be aware of when upgrading a Vitess production installation to a newer Vitess release. + +Generally speaking, upgrading Vitess is a safe and easy process because it is explicitly designed for it. This is because at YouTube we followed the practice of releasing new versions often (usually from the tip of the Git primary branch). + +## Compatibility + +Our versioning strategy is based on [Semantic Versioning](http://semver.org/). + +Vitess version numbers follow the format `MAJOR.MINOR.PATCH`. We guarantee compatibility when upgrading to a newer **patch** or **minor** version. Upgrades to a higher **major** version may require manual configuration changes. + +In general, always **read the 'Upgrading' section of the release notes**. It will mention any incompatible changes and necessary manual steps. + +## Upgrade Order + +We recommend upgrading Vitess using a bottom up approach starting with the vttablet instances and ending with application updates. Upgrades and restarts for vttablets should be handled one at a time, in a rotating fashion, with the primary tablet being last. All components will need restarts after applying upgrades. + +Please use this upgrade order (unless otherwise noted in the release notes): + +* vttablet +* vtctld +* vtgate +* application code which links client libraries + +## Canary Testing + +Within the vtgate and vttablet components, we recommend to [canary](http://martinfowler.com/bliki/CanaryRelease.html) single instances, keyspaces and cells. Upgraded canary instances can "bake" for several hours or days to verify that the upgrade did not introduce a regression. Eventually, you can upgrade the remaining instances. + +## Rolling Upgrades + +We recommend to automate the upgrade process with a configuration management software. It will reduce the possibility of human errors and simplify the process of managing all instances. + +As of June 2016 we do not have templates for any major open-source configuration management software because our internal upgrade process is based on a proprietary software. Therefore, we invite open-source users to contribute such templates. + +Any upgrade should be a rolling release i.e. usually one tablet at a time within a shard. This ensures that the remaining tablets continue serving live traffic and there is no interruption. + +## Upgrading the Primary Tablet + +The *primary* tablet of each shard should always be updated last in the following manner: + +* verify that all *replica* tablets in the shard have been upgraded +* reparent away from the current *primary* to a *replica* tablet +* upgrade old *primary* tablet diff --git a/content/en/docs/19.0/user-guides/schema-changes/_index.md b/content/en/docs/19.0/user-guides/schema-changes/_index.md new file mode 100644 index 000000000..fd3c9ceb9 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/_index.md @@ -0,0 +1,113 @@ +--- +title: Making Schema Changes +description: +weight: 11 +aliases: ['/docs/schema-management/mysql-schema/', '/docs/user-guides/mysql-schema/', '/docs/user-guides/making-schema-changes/', '/docs/schema-management/schema-changes/', '/docs/user-guides/schema-changes/'] +--- + +This user guide describes the problem space of schema changes and the various approaches you may use with Vitess. + +Quick links: + +- Vitess supports [managed, online schema changes](../schema-changes/managed-online-schema-changes/) using different [strategies](../schema-changes/ddl-strategies/), and with visibility and control over the migration process +- Multiple approaches to [unmanaged schema changes](../schema-changes/unmanaged-schema-changes/), either blocking, or owned by the user/DBA. + +{{< info >}} +It is recommended to use Vitess' managed, online schema changes. +{{< /info >}} + +Some background on schema changes follows. + +## The schema change problem + +Schema change is one of the oldest problems in MySQL and in the relational world in general. With accelerated development and deployment flows, engineers find they need to deploy schema changes sometimes on a daily basis. With the growth of data this task becomes more and more difficult. A direct MySQL `ALTER TABLE` statement is a blocking (no reads nor writes are possible on the migrated table) and resource heavy operation; variants of `ALTER TABLE` include `InnoDB` [Online DDL](https://dev.mysql.com/doc/refman/8.0/en/innodb-online-ddl-operations.html), which allows for some concurrency on a `primary` server, but still blocking on replicas, leading to unacceptable replication lags once the statement hits the replicas. + +MySQL's [Instant DDL](https://dev.mysql.com/doc/refman/8.0/en/innodb-online-ddl-operations.html) brings a much better experience where supported migrations run instantly and without additional load. Where possible, these are generally desired. + +`ALTER TABLE` (non-`INSTANT`) operations are greedy, consume as much CPU/Disk IO as needed, are uninterruptible and uncontrollable. Once the operation has begun, it must run to completion; aborting an `ALTER TABLE` may be more expensive than letting it run through, depending on the progress the migration has made. + +Such direct `ALTER TABLE` is fine in development or possibly staging environments, where datasets are either small, or where table locking is acceptable. + +## ALTER TABLE solutions + +Busy production systems tend to use either of these two approaches, to make schema changes less disruptive to ongoing production traffic: + +- Using general purpose online schema change tools, such as [gh-ost](https://github.com/github/gh-ost) and [pt-online-schema-change](https://www.percona.com/doc/percona-toolkit/3.0/pt-online-schema-change.html). These tools _emulate_ an `ALTER TABLE` statement by creating a _ghost_ table in the new desired format, and slowly working through copying data from the existing table, while also applying ongoing changes throughout the migration. + - Vitess offers a built in online schema change flow based on VReplication, and additionally supports `gh-ost` and `pt-online-schema-change`. + - Online schema change tools can be throttled on high load, and can be interrupted at will. +- Run the migration independently on replicas; when all replicas have the new schema, demote the `primary` and promote a `replica` as the new `primary`; then, at leisure, run the migration on the demoted server. Two considerations if using this approach are: + - Each migration requires a failover (aka _successover_, aka _planned reparent_). + - Total wall clock time is higher since we run the same migration in sequence on different servers. + +## Schema change cycle and operation + +The cycle of schema changes, from idea to production, is complex, involves multiple environments and possibly multiple teams. Below is one possible breakdown common in production. Notice how even interacting with the database itself takes multiple steps: + +1. Design: the developer designs a change, tests locally +2. Publish: the developer requests a review of their changes (e.g. on a Pull Request) +3. Review: developer's colleagues and database engineers to check the changes and their impact +4. Formalize: what is the precise `ALTER TABLE` statement to be executed? If running with `gh-ost` or `pt-online-schema-change`, what are the precise command line flags? +5. Locate: where does this change need to go? Which keyspace/cluster? Is this cluster sharded? What are the shards? + Having located the affected MySQL clusters, which is the `primary` server per cluster? +6. Schedule: is there an already running migration on the relevant keyspace/cluster(s)? +7. Execute: invoke the command. In the time we waited, did the identity of `primary` servers change? +8. Audit/control: is the migration in progress? Do we need to abort for some reason? +9. Cut-over/complete: a potential manual step to complete the migration process +10. Cleanup: what do you do with the old tables? An immediate `DROP` is likely not advisable. What's the alternative? +11. Notify user: let the developer know their changes are now in production. +12. Deploy & merge: the developer completes their process. + +Steps `4` - `10` are tightly coupled with the database or with the infrastructure around the database. + +## Schema change and Vitess + +Vitess solves or automates multiple parts of the flow: + +### Formalize + +In [managed, online schema changes](../schema-changes/managed-online-schema-changes/) the user supplies a valid SQL `ALTER TABLE` statement, and Vitess [schedules and runs](../../../design-docs/online-ddl/scheduler/) the migration, based on a specified [strategy](../schema-changes/ddl-strategies/). + +In addition, `vitess` strategy migrations offer [declarative](../schema-changes/declarative-migrations/) changes, where the user only needs to supply the desired `CREATE TABLE` or `DROP TABLE` statements, and Vitess computes the correct migration needed. + +### Locate + +For a given table in a given keyspace, Vitess knows at all times: + +- In which shards (MySQL clusters) the table is found +- Which is the `primary` server per shard. + +When using either managed schema changes, or direct schema changes via `vtctl` or `vtgate`, Vitess resolves the discovery of the affected servers automatically, and this is hidden from the user. + +### Schedule + +In managed, online schema changes, Vitess owns and tracks all pending and active migrations. Vitess schedules migrations to run, either sequentially or, where possible, [concurrently](../schema-changes/concurrent-migrations/). + +### Execute + +In managed, online schema changes, Vitess owns the execution of `vitess`, `gh-ost` or `pt-online-schema-change` migrations. While these run in the background, Vitess keeps track of the migration state. + +In direct schema changes via `vtctl` or `vtgate`, Vitess issues a synchronous `ALTER TABLE` statement on the relevant shards. + +### Audit/control + +In managed, online schema changes, Vitess keeps track of the state of the migration. It automatically detects when the migration is complete or has failed. It will detect failure even if the tablet itself, which is running the migration, fails. Vitess allows the user to cancel a migration. If such a migration is queued by the scheduler, then it is unqueued. If it's already running, it is interrupted and aborted. Vitess allows the user to check on a migration status across the relevant shards. + +### Cut-over/complete + +By default, Vitess runs automated cut-overs. The migration will complete as soon as it's able to. Optionally, the user may request to [postpone](../schema-changes/postponed-migrations/) the migration's completion until an explicit `COMPLETE` command is given. + +### Cleanup + +Vitess automatically garbage-collects the "old" tables, artifacts of `vitess`, `gh-ost` and `pt-online-schema-change` migrations. It drops those tables in an incremental, non blocking method. + +In the case of managed, online schema changes via `pt-online-schema-change`, Vitess will ensure to drop the triggers in case the tool failed to do so for whatever reason. + +## The various approaches + +Vitess allows a variety of approaches to schema changes, from fully automated to fully owned by the user. + +- Managed, online schema changes are the preferred approach in Vitess . +- Direct, blocking ALTERs are generally impractical in production given that they can block writes for substantial lengths of time. +- User controlled migrations are allowed, and under the user's responsibility. + +See breakdown in [managed, online schema changes](../schema-changes/managed-online-schema-changes/) and in [unmanaged schema changes](../schema-changes/unmanaged-schema-changes/). diff --git a/content/en/docs/19.0/user-guides/schema-changes/advanced-usage.md b/content/en/docs/19.0/user-guides/schema-changes/advanced-usage.md new file mode 100644 index 000000000..a38be59b9 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/advanced-usage.md @@ -0,0 +1,190 @@ +--- +title: Advanced usage +weight: 20 +aliases: ['/docs/user-guides/schema-changes/advanced-usage/'] +--- + +Listed below are recipes for advanced online DDL usage: + +- [Duplicate migration detection](#duplicate-migration-detection) +- [Duplicate migration indication](#duplicate-migration-indication) +- [Near instant REVERTs](#near-instant-reverts) + +## Duplicate migration detection + +Two migrations sharing the same context and DDL are considered duplicate, and only one will run to completion. + +Consider this DDL: + +```sql +alter table `customer` add column `status` int unsigned not null; +``` + +You can only run this change successfully once. Once it it applied, the column `status` exists; any attempt to run the migration again yields an error. + +Sometimes it is desirable to be able to retry a migration. For example, if you apply a migration on a sharded keyspace, where one or more of the shards can be down. In such scenario some shards receive and apply the DDL, while other shards do not, and are not aware of its existence. Attempting to re-apply the same DDL will generate errors on the shards that have received and applied it on the first attempt. + +`vtctldclient ApplySchema` accepts a `--migration_context` flag. By default, Vitess auto-generates a unique context per execution of `vtctldclient ApplySchema`. You may supply your own value, which can be an arbitrary text (limited to `1024` characters). You may search for migrations with a particular context via `SHOW VITESS_MIGRATIONS LIKE ''`. Also, any `SHOW VITESS_MIGRATIONS ...` command outputs the context value in the `migration_context` column. + +When Vitess meets a migration which has exact same DDL and exact same (non-empty) context as some older migration, it considers it as a _duplicate_. The new migration does get a `UUID` of its own, and is tracked as a new migration. But if the previous migration (or, if there are multiple past duplicate migrations with same DDL and context, _any one of those_) is `complete`, then the new migration is also implicitly assumed to be `complete`. + +Thus, the new migration does not get to execute if an identical previous migration was successful. + +Usage: + +```sh +$ vtctldclient ApplySchema -- --migration_context="1111-2222" --ddl_strategy='vitess' --sql "alter table customer add column status int unsigned not null" commerce + +$ vtctldclient ApplySchema -- --migration_context="1111-2222" --ddl_strategy='vitess' --sql "alter table customer add column status int unsigned not null" commerce +``` + +In the above, the two calls are identical. Specifically, they share the exact same `--migration_context` value of `1111-2222`, and the exact same `--sql`. + +Notes: + +- As mentioned, the new migration will have its own `UUID`. +- The new migration does get to be scheduled. +- It will only be marked as `complete` if one previous identical migration (same DDL, same non-empty context) is likewise `complete`. +- If, for example, there's a single previous identical migration which is `failed`, the new migration gets to be executed. +- Continuing the above example: if the new migration is successful, the previous migration remains in `failed` state. +- The decision whether to run the migration or to mark it as implicitly `complete` only takes place when the migration is scheduled to run. + +The context may also be set via VTGate: + +```sql +mysql> set @@ddl_strategy='vitess --'; +mysql> set @@migration_context='1111-2222'; +mysql> alter table customer add column status int unsigned not null; +``` + +By default, the migration context for an Online DDL issued via VTGate is the value of `@@session_uuid`. If `@@migration_context` is non-empty, then its value is used. + +## Duplicate migration indication + +You may go one step beyond [duplicate migration detection](#duplicate-migration-detection) by explicitly supplying migration UUIDs such that duplicate migrations are never submitted in the first place. + +Consider the following example, note `--uuid_list` flag: + +```sh +$ vtctldclient ApplySchema -- --uuid_list "73380089_7764_11ec_a656_0a43f95f28a3" --ddl_strategy='vitess' --sql "alter table customer add column status int unsigned not null" commerce + +$ vtctldclient ApplySchema -- --uuid_list "73380089_7764_11ec_a656_0a43f95f28a3" --ddl_strategy='vitess' --sql "alter table customer add column status int unsigned not null" commerce +``` + +Normally Vitess generates a `UUID` for each migration, thus having a new, unique ID per migration. With `-uuid_list`, you can force Vitess into using your own supplied UUID. There cannot be two migrations with the same `UUID`. Therefore, any subsequent submission of a migration with an already existing `UUID` is implicitly discarded. The 2nd call does return the migration `UUID`, but is internally discarded. + +This feature is useful for external management systems (e.g. schema deployment tools) which may want to control the identity of migrations. The external systems are thus able to own the UUID and can re-submit at will. + +Notes: + +- `--uuid_list` accepts zero or more comma separated UUID values +- If empty, Vitess calculates UUID for the migrations +- Number of supplied UUIDs must match the number of DDL statements in `--sql` +- Each UUID must be in [RFC 4122](http://www.ietf.org/rfc/rfc4122.txt) format, with underscored instead of dashes. Examples of valid UUIDs: `73380089_7764_11ec_a656_0a43f95f28a3` and `28dc5ebc_78e6_11ec_accf_ab29e6ca1002`. +- If multiple UUIDs are given, they must all be different from one another. +- It is the caller's responsibility to ensure the UUIDs are indeed unique. If the user submits an `ApplySchema` with an already existing `--uuid_list=` value, Vitess takes no steps to validate whether the DDL is identical to the already existing submission. + +## Gated cut-over + +Some migrations only make sense to run together; or, rather, it's desirable that they complete at the same time. This can be true: + +- For multiple table changes in a single shard, and/or: +- For a table change across multiple shards. + +The user may submit multiple migrations such that non auto-completes. The user can gather information as to whether all migrations are in a good position to complete, termed "ready to complete". The user may then invoke a `COMPLETE` command such that all migrations complete closely (but not atomically) to one another. + +Consider the following: + +```sh +$ vtctldclient ApplySchema --ddl_strategy='vitess --postpone-completion --allow-concurrent' --sql "alter table customer add column country int not null default 0; alter table order add column shipping_country int not null default 0" commerce +29231906_776f_11ec_a656_0a43f95f28a3 +3cc4ae0e_776f_11ec_a656_0a43f95f28a3 +``` + +The combination of `--postpone-completion --allow-concurrent` means migration start sequentially, but at some point all (two in our example) end up running [concurrently](../concurrent-migrations/). + +A `show vitess_migrations like '29231906_776f_11ec_a656_0a43f95f28a3'` presents the column `ready_to_complete`, with values `0` (not ready) or `1` (ready). + +When all migrations for the relevant UUIDs show `1` for `ready_to_complete`, the user can then either: + +```sh +$ vtctldclient ApplySchema --sql "alter vitess_migration complete all" commerce +``` + +Assuming these are the only migrations awaiting completion, or, explicitly issue a complete for each of the migrations: + +```sh +$ vtctldclient ApplySchema --sql "alter vitess_migration '29231906_776f_11ec_a656_0a43f95f28a3' complete all" commerce +$ vtctldclient ApplySchema --sql "alter vitess_migration '3cc4ae0e_776f_11ec_a656_0a43f95f28a3' complete all" commerce +``` + +## Near instant REVERTs + +A [REVERT](../revertible-migrations/) operation is available for `CREATE`, `DROP` and `ALTER` statements. Both `CREATE` and `DROP` reverts are near instantaneous by design. An `ALTER`'s revert is fast, but not instantaneous. While it does not need to copy any table data, hence not proportional to table size and migration runtime, it does need to apply any changes made to the table since migration completion. This means tracking and applying binary log events, and the operation runtime is generally proportional to the time elapsed since migration completion. + +It is possible to preemptively initiate an "open-ended" revert, such that a new workflow prepares the grounds for a revert, but requires a user interaction to actually cut over. + +The use case and workflow is as follows: + +- A long migration runs. The user suspects there might be a risk to the schema change +- As soon as the migration completes, the user issues an open ended revert, preparing the ground to undoing the schema change +- The open ended revert keeps track of binary log changes via VReplication +- If the original migration turns out to be fine, the user cancels the revert +- If the original migration has negative impact, the user completes the revert (thus undoing the schema change) + +Consider the following example. We run a 5 hour long migration to drop an index: + +```sh +$ vtctldclient ApplySchema --ddl_strategy='vitess' --sql "alter table customer drop index joined_timestamp_idx" commerce +29231906_776f_11ec_a656_0a43f95f28a3 +``` + +As soon as the migration completes, we run: + +```sh +$ vtctldclient ApplySchema --ddl_strategy='vitess --postpone-completion --allow-concurrent' --sql "revert vitess_migration '29231906_776f_11ec_a656_0a43f95f28a3'" commerce +3cc4ae0e_776f_11ec_a656_0a43f95f28a3 +``` + +The above begins a `REVERT` migration that is open-ended (does not complete), via `--postpone-completion`. We also request the migration to run concurrently via `--allow-concurrent` such that it does not block any further "normal" migrations on other tables. Note `3cc4ae0e_776f_11ec_a656_0a43f95f28a3` is the UUID for the reverted migration. + +Finally, if we are satisfied that the `drop index` migration went well, we issue: + +```sh +$ vtctldclient ApplySchema --sql "alter vitess_migration '3cc4ae0e_776f_11ec_a656_0a43f95f28a3' cancel" commerce +``` + +That is, we cancel the `REVERT` operation. + +Or, should we have not dropped the index? If our migration seems to have been wrong, we run: + +```sh +$ vtctldclient ApplySchema --sql "alter vitess_migration '3cc4ae0e_776f_11ec_a656_0a43f95f28a3' complete" commerce +``` + +Which means we want to apply the revert. Since the revert is already running in the background, it is likely that binary log processing is up to date, and cut-over is near instantaneous. + +## Inter-dependent migrations + +It is possible to submit inter-dependent migrations within the same `ApplySchema` command, and have them complete in the correct order, even if they run concurrently. Examples for inter-dependent migrations: + +- Creating two new views, one of which reads from the other. +- Adding a column to a table, and creating a new view that reads from that column. +- Adding a column to a table, altering an existing view that reads from that table, to now read the new column. + +In the above examples there has to be a strict ordering to the migrations. You cannot just create a view that reads from a yet non-existent column. + +`vitess` offers the `--in-order-completion` DDL strategy flag. It is the responsibility of the user to supply the migrations in a valid ordering, and it is `vitess`'s responsibility to _complete_ the migrations in that same order. + +Note that there can be scenarios with impossible ordering. Those hardly make sense in production, in the first place, and it is the user's responsibility to supply a sequence that works. When in doubt, it's advisable to submit migrations in stages: only apply one migration to completion, and then apply another. + +An example for in-order submission: + +```sh +$ vtctldclient ApplySchema --ddl_strategy='vitess --allow-concurrent --in-order-completion' --sql "create table t1 (id int primary key); create view v1 as select id from t1;" commerce +``` + +{{< info >}} +- `--allow-concurrent` is optional, but is likely to be the main use case for using in-order completion. +- in-order completion also works with `--postpone-launch` and `--postpone-completion`. +{{< /info >}} diff --git a/content/en/docs/19.0/user-guides/schema-changes/audit-and-control.md b/content/en/docs/19.0/user-guides/schema-changes/audit-and-control.md new file mode 100644 index 000000000..b2b3d5f9f --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/audit-and-control.md @@ -0,0 +1,796 @@ +--- +title: Applying, auditing, and controlling Online DDL +weight: 6 +aliases: ['/docs/user-guides/managed-online-schema-changes/audit-and-control'] +--- + +Vitess provides two interfaces to interacting with Online DDL: + +- SQL commands, via `VTGate` +- Command line interface, via `vtctl` + +Supported interactions are: + +- [Running migrations](#running-migrations) (submitting Online DDL requests) +- [Tracking migrations](#tracking-migrations) +- [Launching a migration](#launching-a-migration) or all migrations, if explicitly set to postpone launch. +- [Completing a migration](#completing-a-migration) or all migrations, if explicitly set to postpone completion. +- [Cancelling a migration](#cancelling-a-migration) +- [Cancelling a migration](#cancelling-a-migration) +- [Cancelling all pending migrations](#cancelling-all-keyspace-migrations) +- [Retrying a migration](#retrying-a-migration) +- [Cleaning migration artifacts](#cleaning-migration-artifacts) +- [Reverting a migration](#reverting-a-migration) + +## Running migrations + +To run a managed schema migration, you should: + +- Formulate your DDLs (`CREATE`, `ALTER`, `DROP`) queries +- Choose a [ddl_strategy](../ddl-strategies) + +When the user submits an online DDL, Vitess responds with a UUID, a job Id used to later track or control the migration. The migration does not start immediately. It is queued at the tablets and executed at some point in the future. + +#### Via VTGate/SQL + +```sql +mysql> set @@ddl_strategy='vitess'; + +mysql> alter table corder add column ts timestamp not null default current_timestamp; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| bf4598ab_8d55_11eb_815f_f875a4d24e90 | ++--------------------------------------+ + +mysql> drop table customer; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 6848c1a4_8d57_11eb_815f_f875a4d24e90 | ++--------------------------------------+ +``` + +- `@@ddl_strategy` behaves like a MySQL session variable, though is only recognized by `VTGate`. Setting `@@ddl_strategy` only applies to that same connection and does not affect other connections. The strategy applies to all migrations executed in that session. You may subsequently set `@@ddl_strategy` to different value. +- If you run `vtgate` without `--ddl_strategy`, then `@@ddl_strategy` defaults to `'direct'`, which implies schema migrations are synchronous. You will need to `set @@ddl_strategy='gh-ost'` to run followup `ALTER TABLE` statements via `gh-ost`. +- If you run `vtgate --ddl_strategy "gh-ost"`, then `@@ddl_strategy` defaults to `'gh-ost'` in each new session. Any `ALTER TABLE` will run via `gh-ost`. You may `set @@ddl_strategy='pt-osc'` to make migrations run through `pt-online-schema-change`, or `set @@ddl_strategy='direct'` to run migrations synchronously. + +#### Via vtctlclient/ApplySchema + +You may use `vtctl` or `vtctlclient` (the two are interchangeable for the purpose of this document) to apply schema changes. The `ApplySchema` command supports both synchronous and online schema migrations. To run an online schema migration you will supply the `--ddl_strategy` command line flag: + +```shell +$ vtctldclient ApplySchema --ddl-strategy "vitess" --sql "ALTER TABLE demo MODIFY id bigint UNSIGNED" commerce +a2994c92_f1d4_11ea_afa3_f875a4d24e90 +``` + + You my run multiple migrations withing the same `ApplySchema` command: +```shell +$ vtctldclient ApplySchema --ddl-strategy "vitess" --sql "ALTER TABLE demo MODIFY id bigint UNSIGNED; CREATE TABLE sample (id int PRIMARY KEY); DROP TABLE another;" commerce +3091ef2a_4b87_11ec_a827_0a43f95f28a3 +``` + +`ApplySchema` accepts the following flags: + +- `--ddl_strategy`: by default migrations run directly via MySQL standard DDL. This flag must be aupplied to indicate an online strategy. See also [DDL strategies](../ddl-strategies) and [ddl_strategy flags](../ddl-strategy-flags). +- `--migration_context `: all migrations in a `ApplySchema` command are logically grouped via a unique _context_. A unique value will be supplied automatically. The user may choose to supply their own value, and it's their responsibility to provide with a unique value. Any string format is accepted. + The context can then be used to search for migrations, via `SHOW VITESS_MIGRATIONS LIKE 'the-context'`. It is visible in `SHOW VITESS_MIGRATIONS ...` output as the `migration_context` column. + +## Tracking migrations + +You may track the status of a single or of multiple migrations. Since migrations run asycnhronously, it is the user's responsibility to audit the progress and state of submitted migrations. Users are likely to want to know when a migration is complete (or failed) so as to be able to deploy code changes or run other operations. + +Common patterns are: + +- Show state of a specific migration +- Show all `running`, `complete` or `failed` migrations +- Show recent migrations +- Show migrations ordered by most-recent first. +- Show n number of migrations, skipping m rows. + +#### Via VTGate/SQL + +Examples for a single shard cluster: + +```sql +mysql> show vitess_migrations like 'bf4598ab_8d55_11eb_815f_f875a4d24e90' \G +*************************** 1. row *************************** + id: 23 + migration_uuid: bf4598ab_8d55_11eb_815f_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: corder +migration_statement: alter table corder add column ts timestamp not null default current_timestamp() + strategy: vitess + options: + added_timestamp: 2021-03-25 12:35:01 +requested_timestamp: 2021-03-25 12:34:58 + ready_timestamp: 2021-03-25 12:35:04 + started_timestamp: 2021-03-25 12:35:04 + liveness_timestamp: 2021-03-25 12:35:06 +completed_timestamp: 2021-03-25 12:35:06 + cleanup_timestamp: NULL + migration_status: complete + log_path: + artifacts: _bf4598ab_8d55_11eb_815f_f875a4d24e90_20210325123504_vrepl, + retries: 0 + tablet: zone1-0000000100 + tablet_failure: 0 + progress: 100 + migration_context: vtgate:a8352418-8d55-11eb-815f-f875a4d24e90 + ddl_action: alter + message: + eta_seconds: 0 +``` + +```sql +mysql> show vitess_migrations like 'complete' \G +... +*************************** 21. row *************************** + id: 24 + migration_uuid: 6848c1a4_8d57_11eb_815f_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: customer +migration_statement: drop table customer + strategy: vitess + options: + added_timestamp: 2021-03-25 12:46:53 +requested_timestamp: 2021-03-25 12:46:51 + ready_timestamp: 2021-03-25 12:46:57 + started_timestamp: 2021-03-25 12:46:57 + liveness_timestamp: 2021-03-25 12:46:57 +completed_timestamp: 2021-03-25 12:46:57 + cleanup_timestamp: NULL + migration_status: complete + log_path: + artifacts: _vt_HOLD_6848c1a48d5711eb815ff875a4d24e90_20210326104657, + retries: 0 + tablet: zone1-0000000100 + tablet_failure: 0 + progress: 100 + migration_context: vtgate:a8352418-8d55-11eb-815f-f875a4d24e90 + ddl_action: drop + message: + eta_seconds: 0 +``` + +```sql +mysql> show vitess_migrations where completed_timestamp > now() - interval 1 day; ++----+--------------------------------------+----------+-------+--------------+-------------+---------------------------------------------------------------------------------+----------+---------+---------------------+---------------------+---------------------+---------------------+---------------------+---------------------+-------------------+------------------+----------+-------------------------------------------------------------+---------+------------------+----------------+----------+---------------------------------------------+------------+---------+-------------+ +| id | migration_uuid | keyspace | shard | mysql_schema | mysql_table | migration_statement | strategy | options | added_timestamp | requested_timestamp | ready_timestamp | started_timestamp | liveness_timestamp | completed_timestamp | cleanup_timestamp | migration_status | log_path | artifacts | retries | tablet | tablet_failure | progress | migration_context | ddl_action | message | eta_seconds | ++----+--------------------------------------+----------+-------+--------------+-------------+---------------------------------------------------------------------------------+----------+---------+---------------------+---------------------+---------------------+---------------------+---------------------+---------------------+-------------------+------------------+----------+-------------------------------------------------------------+---------+------------------+----------------+----------+---------------------------------------------+------------+---------+-------------+ +| 23 | bf4598ab_8d55_11eb_815f_f875a4d24e90 | commerce | 0 | vt_commerce | corder | alter table corder add column ts timestamp not null default current_timestamp() | online | | 2021-03-25 12:35:01 | 2021-03-25 12:34:58 | 2021-03-25 12:35:04 | 2021-03-25 12:35:04 | 2021-03-25 12:35:06 | 2021-03-25 12:35:06 | NULL | complete | | _bf4598ab_8d55_11eb_815f_f875a4d24e90_20210325123504_vrepl, | 0 | zone1-0000000100 | 0 | 100 | vtgate:a8352418-8d55-11eb-815f-f875a4d24e90 | alter | | 0 | +| 24 | 6848c1a4_8d57_11eb_815f_f875a4d24e90 | commerce | 0 | vt_commerce | customer | drop table customer | online | | 2021-03-25 12:46:53 | 2021-03-25 12:46:51 | 2021-03-25 12:46:57 | 2021-03-25 12:46:57 | 2021-03-25 12:46:57 | 2021-03-25 12:46:57 | NULL | complete | | _vt_HOLD_6848c1a48d5711eb815ff875a4d24e90_20210326104657, | 0 | zone1-0000000100 | 0 | 100 | vtgate:a8352418-8d55-11eb-815f-f875a4d24e90 | drop | | 0 | +| 25 | 6fd57dd3_8d57_11eb_815f_f875a4d24e90 | commerce | 0 | vt_commerce | customer | revert 6848c1a4_8d57_11eb_815f_f875a4d24e90 | online | | 2021-03-25 12:47:08 | 2021-03-25 12:47:04 | 2021-03-25 12:47:12 | 2021-03-25 12:47:12 | 2021-03-25 12:47:12 | 2021-03-25 12:47:12 | NULL | complete | | _vt_HOLD_6848c1a48d5711eb815ff875a4d24e90_20210326104657, | 0 | zone1-0000000100 | 0 | 100 | vtgate:a8352418-8d55-11eb-815f-f875a4d24e90 | create | | 0 | ++----+--------------------------------------+----------+-------+--------------+-------------+---------------------------------------------------------------------------------+----------+---------+---------------------+---------------------+---------------------+---------------------+---------------------+---------------------+-------------------+------------------+----------+-------------------------------------------------------------+---------+------------------+----------------+----------+---------------------------------------------+------------+---------+-------------+ +``` + +- `show vitess_migrations` shows the entire history of migrations. +- `show vitess_migrations like ...` filters migrations by `migration_uuid`, or `migration_context`, or `migration_status`. +- `show vitess_migrations where ...` lets the user specify arbitrary conditions. +- All commands return results for the keyspace (schema) in use. + +#### Via vtctlclient/ApplySchema + +Examples for a 4-shard cluster: + +```shell +$ vtctlclient OnlineDDL commerce show ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000201 | 40-80 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:24:33 | 2020-09-09 05:24:34 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000401 | c0- | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000101 | -40 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce show 8a797518_f25c_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000401 | c0- | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | running | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | 2020-09-09 05:23:33 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | running | +| test-0000000101 | -40 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | running | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce show 8a797518_f25c_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000401 | c0- | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000101 | -40 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | 2020-09-09 05:23:33 | complete | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce show recent ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | 2020-09-09 05:23:33 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:24:33 | 2020-09-09 05:24:34 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000401 | c0- | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000401 | c0- | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000401 | c0- | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000101 | -40 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000101 | -40 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000101 | -40 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL --order descending commerce show all ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000101 | -40 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000101 | -40 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000101 | -40 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000401 | c0- | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000401 | c0- | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000401 | c0- | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:24:33 | 2020-09-09 05:24:34 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | 2020-09-09 05:23:33 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce show failed ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000401 | c0- | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000101 | -40 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL --limit 5 commerce show recent ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | 2020-09-09 05:23:33 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:24:33 | 2020-09-09 05:24:34 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL --skip 5 --limit 5 commerce show recent ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000401 | c0- | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:25:13 | 2020-09-09 05:25:14 | complete | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 8a797518_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:23:32 | | failed | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 63b5db0c_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:22:41 | 2020-09-09 05:22:42 | complete | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | ab3ffdd5_f25c_11ea_bab4_0242c0a8b007 | online | 2020-09-09 05:24:33 | 2020-09-09 05:24:34 | complete | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +``` +The syntax for tracking migrations is: +``` +vtctlclient OnlineDDL [-json] show +``` + + + +## Showing migration logs + +`gh-ost` and `pt-osc` tools generate logs files, which are retrievable for `24` hours after migration completion/failure. + +#### Via VTGate/SQL + +```sql +mysql> show vitess_migration '3a273866_e867_11eb_ab12_0a43f95f28a3' logs \G +*************************** 1. row *************************** +migration_log: 2021-07-19 07:59:23 INFO starting gh-ost 261355426d8fc31b590733ca8ff8e79012103c18 +2021-07-19 07:59:23 INFO Migrating `vt_commerce`.`corder` +2021-07-19 07:59:23 INFO executing gh-ost-on-startup hook: /tmp/online-ddl-3a273866_e867_11eb_ab12_0a43f95f28a3-943208852/gh-ost-on-startup +ok +2021-07-19 07:59:23 INFO inspector connection validated on ip-REDACTED:17100 +2021-07-19 07:59:23 INFO User has SUPER, REPLICATION SLAVE privileges, and has ALL privileges on `vt_commerce`.* +2021-07-19 07:59:23 INFO binary logs validated on ip-REDACTED:17100 +2021-07-19 07:59:23 INFO Restarting replication on ip-REDACTED:17100 to make sure binlog settings apply to replication thread +2021-07-19 07:59:23 INFO Inspector initiated on ip-REDACTED:17100, version 5.7.30-log +2021-07-19 07:59:23 INFO Table found. Engine=InnoDB +... +``` + +## Launching a migration + +Migrations submitted with [`--postpone-launch`](../postponed-migrations) remain `queued` or `ready` until told to launch. The user may launch a specific migration or they may launch all postponed migrations: + +#### Via VTGate/SQL + +```sql +mysql> alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' launch; +Query OK, 1 row affected (0.01 sec) +``` + +or + +```sql +mysql> alter vitess_migration launch all; +Query OK, 1 row affected (0.01 sec) +``` + +#### Via vtctlclient/ApplySchema + +Launch a specific migration: + +```shell +$ vtctldclient ApplySchema --sql "alter vitess_migration '9e8a9249_3976_11ed_9442_0a43f95f28a3' launch" commerce +``` + +Or launch a specific migration on a specific shard: + +```shell +$ vtctldclient ApplySchema --sql "alter vitess_migration '9e8a9249_3976_11ed_9442_0a43f95f28a3' launch vitess_shards '-40,40-80'" commerce +``` + +Or launch all: + +```shell +$ vtctldclient ApplySchema --sql "alter vitess_migration launch all" commerce +``` + +## Completing a migration + +Migrations submitted with [`--postpone-completion`](../postponed-migrations) remain `ready` or `running` until told to complete. The user may complete a specific migration or they may complete all postponed migrations: + +#### Via VTGate/SQL + +```sql +mysql> alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' complete; +Query OK, 1 row affected (0.01 sec) +``` + +or + +```sql +mysql> alter vitess_migration complete all; +Query OK, 1 row affected (0.01 sec) +``` + +#### Via vtctlclient/ApplySchema + +Complete a specific migration: + +```shell +$ vtctldclient ApplySchema --sql "alter vitess_migration '9e8a9249_3976_11ed_9442_0a43f95f28a3' complete" commerce +``` + +Or complete all: + +```shell +$ vtctldclient ApplySchema --sql "alter vitess_migration complete all" commerce +``` + +## Cancelling a migration + +The user may cancel a migration, as follows: + +- If the migration hasn't started yet (it is `queued` or `ready`), then it transitions into `cancelled` state and doesn't get executed. +- If the migration is `running`, then it is forcibly interrupted. The migration transitions to `cancelled` state. +- In all other cases, cancelling a migration has no effect. + +#### Via VTGate/SQL + +Examples for a single shard cluster: + + +```sql + id: 28 + migration_uuid: aa89f255_8d68_11eb_815f_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: corder +migration_statement: alter table corder add column handler_id int not null + strategy: gh-ost + options: + added_timestamp: 2021-03-25 14:50:27 +requested_timestamp: 2021-03-25 14:50:24 + ready_timestamp: 2021-03-25 14:50:31 + started_timestamp: 2021-03-25 14:50:32 + liveness_timestamp: 2021-03-25 14:50:32 +completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: running +... + +mysql> alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' cancel; +Query OK, 1 row affected (0.01 sec) + +mysql> show vitess_migrations like 'aa89f255_8d68_11eb_815f_f875a4d24e90' \G +*************************** 1. row *************************** + id: 28 + migration_uuid: aa89f255_8d68_11eb_815f_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: corder +migration_statement: alter table corder add column handler_id int not null + strategy: gh-ost + options: --throttle-flag-file=/tmp/throttle.flag + added_timestamp: 2021-03-25 14:50:27 +requested_timestamp: 2021-03-25 14:50:24 + ready_timestamp: 2021-03-25 14:50:31 + started_timestamp: 2021-03-25 14:50:32 + liveness_timestamp: 2021-03-25 14:50:32 +completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: cancelled +... +``` + +- `alter vitess_migration ... cancel` takes exactly one migration's UUID. +- `alter vitess_migration ... cancel` responds with number of affected migrations. + +#### Via vtctlclient/ApplySchema + +Examples for a 4-shard cluster: + +``` +vtctlclient OnlineDDL cancel +``` + +Example: + +```shell +$ vtctlclient OnlineDDL commerce show 2201058f_f266_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | running | +| test-0000000101 | -40 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | running | +| test-0000000401 | c0- | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | running | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | running | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce cancel 2201058f_f266_11ea_bab4_0242c0a8b007 + +$ vtctlclient OnlineDDL commerce show 2201058f_f266_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000401 | c0- | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | cancelled | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | cancelled | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | cancelled | +| test-0000000101 | -40 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | cancelled | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +``` + + +## Cancelling all keyspace migrations + +The user may cancel all migrations in a keyspace. A migration is cancellable if it is in `queued`, `ready` or `running` states, as described previously. It is a high impact operation and should be used with care. + +#### Via VTGate/SQL + +Examples for a single shard cluster: + +```sql +mysql> alter vitess_migration cancel all; +Query OK, 1 row affected (0.02 sec) +``` + +#### Via vtctlclient/ApplySchema + +Examples for a 4-shard cluster: + + +```shell +$ vtctldclient ApplySchema --sql "alter vitess_migration cancel all" commerce +``` + +Also available via `vtctlclient OnlineDDL` command: + +``` +vtctlclient OnlineDDL cancel all +``` + +Example: + +```shell +$ vtctlclient OnlineDDL commerce show all ++------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ +| zone1-0000000100 | 0 | vt_commerce | corder | 2c581994_353a_11eb_8b72_f875a4d24e90 | online | | | queued | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c6420c9_353a_11eb_8b72_f875a4d24e90 | online | | | queued | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c7040df_353a_11eb_8b72_f875a4d24e90 | online | | | queued | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c7c0572_353a_11eb_8b72_f875a4d24e90 | online | | | queued | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c87f7cd_353a_11eb_8b72_f875a4d24e90 | online | | | queued | ++------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce cancel all + +$ vtctlclient OnlineDDL commerce show all ++------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ +| zone1-0000000100 | 0 | vt_commerce | corder | 2c581994_353a_11eb_8b72_f875a4d24e90 | online | | | cancelled | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c6420c9_353a_11eb_8b72_f875a4d24e90 | online | | | cancelled | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c7040df_353a_11eb_8b72_f875a4d24e90 | online | | | cancelled | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c7c0572_353a_11eb_8b72_f875a4d24e90 | online | | | cancelled | +| zone1-0000000100 | 0 | vt_commerce | corder | 2c87f7cd_353a_11eb_8b72_f875a4d24e90 | online | | | cancelled | ++------------------+-------+--------------+-------------+--------------------------------------+----------+-------------------+---------------------+------------------+ +``` + +## Retrying a migration + +The user may retry running a migration. If the migration is in `failed` or in `cancelled` state, Vitess will re-run the migration, with exact same arguments as previously intended. If the migration is in any other state, `retry` does nothing. + +It is not possible to retry a migration with different options. e.g. if the user initially runs `ALTER TABLE demo MODIFY id BIGINT` with `@@ddl_strategy='gh-ost --max-load Threads_running=200'` and the migration fails, retrying it will use exact same options. It is not possible to retry with `@@ddl_strategy='gh-ost --max-load Threads_running=500'`. + +#### Via VTGate/SQL + +Examples for a single shard cluster: + +```sql +*************************** 1. row *************************** + id: 28 + migration_uuid: aa89f255_8d68_11eb_815f_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: corder +migration_statement: alter table corder add column handler_id int not null + strategy: gh-ost + options: --throttle-flag-file=/tmp/throttle.flag + added_timestamp: 2021-03-25 14:50:27 +requested_timestamp: 2021-03-25 14:50:24 + ready_timestamp: 2021-03-25 14:56:22 + started_timestamp: 2021-03-25 14:56:22 + liveness_timestamp: 2021-03-25 14:56:22 +completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: failed +... + +mysql> alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' retry; +Query OK, 1 row affected (0.00 sec) + +mysql> show vitess_migrations like 'aa89f255_8d68_11eb_815f_f875a4d24e90' \G +*************************** 1. row *************************** + id: 28 + migration_uuid: aa89f255_8d68_11eb_815f_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: corder +migration_statement: alter table corder add column handler_id int not null + strategy: gh-ost + options: --throttle-flag-file=/tmp/throttle.flag + added_timestamp: 2021-03-25 14:50:27 +requested_timestamp: 2021-03-25 14:50:24 + ready_timestamp: 2021-03-25 14:56:42 + started_timestamp: 2021-03-25 14:56:42 + liveness_timestamp: 2021-03-25 14:56:42 +completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: running +... +``` +- `alter vitess_migration ... retry` takes exactly one migration's UUID. +- `alter vitess_migration ... retry` responds with number of affected migrations. + +#### Via vtctlclient/ApplySchema + + +```shell +$ vtctldclient ApplySchema --sql "alter vitess_migration '2201058f_f266_11ea_bab4_0242c0a8b007' retry" commerce +``` + +Also available via `vtctlclient OnlineDDL` command: + +Examples for a 4-shard cluster: + + +```shell +$ vtctlclient OnlineDDL commerce show 2201058f_f266_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000401 | c0- | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | failed | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | failed | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | failed | +| test-0000000101 | -40 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:32:31 | | failed | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce retry 2201058f_f266_11ea_bab4_0242c0a8b007 + +$ vtctlclient OnlineDDL commerce show 2201058f_f266_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+-------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+-------------------+---------------------+------------------+ +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | | | queued | +| test-0000000101 | -40 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | | | queued | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | | | queued | +| test-0000000401 | c0- | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | | | queued | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+-------------------+---------------------+------------------+ + +$ vtctlclient OnlineDDL commerce show 2201058f_f266_11ea_bab4_0242c0a8b007 ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| Tablet | shard | mysql_schema | mysql_table | ddl_action | migration_uuid | strategy | started_timestamp | completed_timestamp | migration_status | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +| test-0000000101 | -40 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:37:33 | | running | +| test-0000000401 | c0- | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:37:33 | | running | +| test-0000000201 | 40-80 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:37:33 | | running | +| test-0000000301 | 80-c0 | vt_commerce | demo | alter | 2201058f_f266_11ea_bab4_0242c0a8b007 | online | 2020-09-09 06:37:33 | | running | ++-----------------+-------+--------------+-------------+------------+--------------------------------------+----------+---------------------+---------------------+------------------+ +``` + +## Cleaning migration artifacts + +Migrations yield artifacts: these are leftover tables, such as the ghost or shadow tables in an `ALTER` DDL. These tables are audited and collected as part of [table lifecycle](../table-lifecycle/). + +The artifacts are essential to [Reverting a migration](../revertible-migrations/), and are kept intact for a while before destroyed. + +However, the artifacts also consume disk space. If the user is convinced they will not need the artifacts, they may explicitly request that the artifacts are dropped sooner. + +{{< warning >}} +Once cleanup is requested, the migration cannot be reverted. +{{< /warning >}} +{{< info >}} +The artifact tables are not purged immediately. Rather, they are sent for processing into the lifecycle mechanism. +{{< /info >}} + +#### Via VTGate/SQL + +Per migration, request artifact cleanup via: + +```sql +mysql> alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' cleanup; +Query OK, 1 row affected (0.00 sec) +``` + + +#### Via vtctlclient/ApplySchema + +Execute via `vtctldclient ApplySchema --sql "..." ` like previous commands, or use `OnlineDDL` command: + + +```shell +$ vtctlclient OnlineDDL commerce cleanup 2201058f_f266_11ea_bab4_0242c0a8b007 +``` + +## Reverting a migration + +Vitess offers _lossless revert_ for online schema migrations: the user may regret a table migration after completion, and roll back the table's schema to previous state _without loss of data_. See [Revertible Migrations](../revertible-migrations/). + +### Via VTGate/SQL + +Examples for a single shard cluster: + +```sql +mysql> show create table corder\G + +Create Table: CREATE TABLE `corder` ( + `order_id` bigint(20) NOT NULL AUTO_INCREMENT, + `customer_id` bigint(20) DEFAULT NULL, + `sku` varbinary(128) DEFAULT NULL, + `price` bigint(20) DEFAULT NULL, + `ts` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (`order_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 +1 row in set (0.01 sec) + +mysql> alter table corder drop column ts, add key customer_idx(customer_id); ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 1a689113_8d77_11eb_815f_f875a4d24e90 | ++--------------------------------------+ + +mysql> show create table corder\G + +Create Table: CREATE TABLE `corder` ( + `order_id` bigint(20) NOT NULL AUTO_INCREMENT, + `customer_id` bigint(20) DEFAULT NULL, + `sku` varbinary(128) DEFAULT NULL, + `price` bigint(20) DEFAULT NULL, + PRIMARY KEY (`order_id`), + KEY `customer_idx` (`customer_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 +1 row in set (0.00 sec) + +mysql> revert vitess_migration '1a689113_8d77_11eb_815f_f875a4d24e90'; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| a02e6612_8d79_11eb_815f_f875a4d24e90 | ++--------------------------------------+ + +mysql> show create table corder\G + +Create Table: CREATE TABLE `corder` ( + `order_id` bigint(20) NOT NULL AUTO_INCREMENT, + `customer_id` bigint(20) DEFAULT NULL, + `sku` varbinary(128) DEFAULT NULL, + `price` bigint(20) DEFAULT NULL, + `ts` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (`order_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 +``` + +- A `revert` is its own migration, hence has its own UUID + +### Via vtctlclient/ApplySchema + +```sh +$ vtctldclient ApplySchema --ddl-strategy "vitess" --sql "revert vitess_migration '1a689113_8d77_11eb_815f_f875a4d24e90'" commerce +``` + +## Controlling throttling + +Managed migrations [use](../managed-online-schema-changes/#throttling) the [tablet throttler](../../../reference/features/tablet-throttler/) to ensure a sustainable impact to the MySQL servers and replication stream. Normally, the user doesn't need to get involved, as the throttler auto-identifies load scenarios, and pushes back on migration progress. However, Vitess makes available these commands for additional control over migration throttling: + +```sql +alter vitess_migration '' throttle [expire ''] [ratio ]; +alter vitess_migration throttle all [expire ''] [ratio ]; +alter vitess_migration '' unthrottle; +alter vitess_migration unthrottle all; +show vitess_throttled_apps; +``` + +**Note:** the tablet throttler must be enabled for these command to run. + +### Throttling a migration + +To fully throttle a migration, run: + +```sql +mysql> alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' throttle; +Query OK, 1 row affected (0.00 sec) +``` + +From this point on, the migration will not make row copy progress and will not apply binary logs. By default, this command does not expire, and it takes an explicit `unthrottle` command to resume migration progress. Because MySQL binary logs are rotated, a migration may only survive a full throttling up to the point where the binary log it last processed is purged. + +You may supply either or both these options: `expire`, `ratio`: + +- `alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' throttle expire '2h'` will fully throttle the migration for the next `2` hours, after which the migration resumes normal work. You may specify these units: `s` (seconds), `m` (minutes), `h` (hours) or combinations. Example values: `90s`, `30m`, `1h`, `1h30m`, etc. +- `alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' throttle ratio 0.7` will partially throttle the migration. This instructs the throttler to reject, on average, `7` migration throttling check requests out of `10`. Any value between `0` (no throttling at all) and `1.0` (fully throttled) are allowed. This is a fine tune way to slow down a migration. + +### Throttling all migrations + +It's likely that you will want to throttle migrations in general, and not a specific migration. Use: + +- `alter vitess_migration throttle all;` to fully throttle any and all migrations from this point on +- `alter vitess_migration throttle all expire '90m';` to fully throttle any and all migrations from this point on and for the next `90` minutes. +- `alter vitess_migration throttle all ratio 0.8;` to severely slow down all migrations from this point on (4 out of 5 migrations requests to the throttler are denied) +- `alter vitess_migration throttle all duration '10m' ratio 0.2;` to lightly slow down all migrations from this point on (1 out of 5 migrations requests to the throttler are denied) for the next `10` minutes. + +### Unthrottling + +Use: + +- `alter vitess_migration 'aa89f255_8d68_11eb_815f_f875a4d24e90' unthrottle;` to allow the specified migration to resume working as normal +- `alter vitess_migration unthrottle all;` to unthrottle all migrations. + +**Note** that this does not disable throttling altogether. If, for example, replication lag grows on replicas, the throttler may still throttle the migration until replication is caught up. Unthrottling only cancels an explicit throttling request as described above. + +### Showing throttled apps + +The command `show vitess_throttled_apps;` is a general purpose throttler command, and shows all apps for which there are throttling rules. It will list any specific or general migration throttling status. + +### Via vtctlclient/ApplySchema + +Execute via `vtctldclient ApplySchema --sql "..." ` like previous commands, or use `OnlineDDL` commands: + + +```shell +$ vtctlclient OnlineDDL commerce throttle 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce throttle all +$ vtctlclient OnlineDDL commerce unthrottle 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce unthrottle all +``` diff --git a/content/en/docs/19.0/user-guides/schema-changes/concurrent-migrations.md b/content/en/docs/19.0/user-guides/schema-changes/concurrent-migrations.md new file mode 100644 index 000000000..aabf08cf1 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/concurrent-migrations.md @@ -0,0 +1,70 @@ +--- +title: Concurrent migration execution +weight: 15 +aliases: ['/docs/user-guides/schema-changes/concurrent-migrations/'] +--- + +By default, Vitess schedules all migrations to run sequentially. Only a single migration is expected to run at any given time. However, there are cases for concurrent execution of migrations, and the user may request concurrent execution via `--allow-concurrent` flag in `ddl_strategy`. + +## Why not run concurrent migrations by default + +At the heart of schema migration management we are interested in `ALTER` DDLs that run for long periods of time. These will copy large amounts of data, perform many reads and writes, and overall affect the production server. They use built-in throttling mechanism to prevent harming production. The migration essentially competes with production traffic over resources. + +Generally speaking, running multiple such migrations concurrently increases resource competition substantially, and yields with overall higher wall clock migrations runtime compared with sequential execution. However, this depends on the _phases_ of the running migrations, as explained next. + +## Phases of a Vitess migration + +A `vitess` `ALTER TABLE` migration runs through several phases, and the two notable ones are: + +- The copy phase +- The tailing phase + +While the two interleave to some extent, it is illustrative to think of a migration as first copying the already existing rows of a table into the shadow table, then proceeding to tail the changelog (the binary logs) and apply events onto the shadow table. + +The copy phase is generally a heavyweight operation, as it incurs a massive copy of data in a greedy (though throttled) approach. The tailing phase could be intensive or relaxed, depending on the incoming production traffic (`INSERT`, `DELETE`, `UPDATE`) to the migrated table. + +Running two concurrent copy phases is, generally speaking, a very heavyweight operation and the two tasks interfere with each other. However, running two or more concurrent tailing phases could be lightweight, depending on incoming traffic. + +## Types of migrations that may run concurrnetly + +There are valid, even essential cases to running multiple migrations concurrently. Vitess supports the following scenarios: + +- Even though a long running `ALTER` may be running, a `CREATE` or `DROP` can be issued concurrently, with little to no effect on the migration and without competing over resources. +- There can be an urgent need to [revert a migration](../revertible-migrations). Vitess can allow reverting a migration (or even multiple migrations) even as some other unrelated migration is in process. +- Two `vitess` migrations could run concurrently: `vitess` will make sure only a single copy-phase runs at a time, but as many (up to some limit, in the dozens) tail phases may run concurrently to each other. + This plays well with [postponed migrations](../postponed-migrations). + +## Running a concurrent migration + +To run a migration concurrently, the user will add `--allow-concurrent` to the `ddl_strategy`. For example: + +```sql +mysql> set @@ddl_strategy='vitess --allow-concurrent'; +mysql> create table sample_table(id int primary key); +``` + +or, via `vtctl`: + +```shell +vtctldclient ApplySchema --ddl-strategy "vitess --allow-concurrent" -sql "REVERT VITESS_MIGRATION '3091ef2a_4b87_11ec_a827_0a43f95f28a3'" +``` + +## Restrictions and eligibility + +- To be eligible for concurrent execution, `--allow-concurrent` must be supplied. +- Any `CREATE` and `DROP` DDL is eligible for concurrent execution. +- Any `REVERT` request is eligible for concurrent execution. +- There can be at most one non-concurrent (regular) migration running at any given time. +- There may be an unlimited number of concurrent migrations running at any given time, on top of potentially a single non-concurrent migration. +- But there will never be two migrations running concurrently that operate on the same table. + +To clarify: + +- `gh-ost` and `pt-osc` `ALTER` migrations are not eligible to run concurrently + +## Scheduling notes + +- Multiple migrations can be in `ready` state. The scheduler will check them one by one to see which is eligible to next run. +- Migrations will advance to `running` state one at a time, at most a few seconds apart. +- A migration can be blocked from `running` if it operates on the same table as an already running migration. +- While one or more migrations can be blocked from `running`, other migrations, even if submitted later, could start running, assuming no concurrency conflicts. diff --git a/content/en/docs/19.0/user-guides/schema-changes/ddl-strategies.md b/content/en/docs/19.0/user-guides/schema-changes/ddl-strategies.md new file mode 100644 index 000000000..f06fedf6c --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/ddl-strategies.md @@ -0,0 +1,178 @@ +--- +title: Online DDL strategies +weight: 3 +aliases: ['/docs/user-guides/schema-changes/ddl-strategies/'] +--- + +Vitess supports both managed, online schema migrations (aka Online DDL) as well as unmanaged migrations. How Vitess runs a schema migration depends on the _DDL strategy_. Vitess allows these strategies: + +- `vitess` (formerly known as `online`): utilizes Vitess's built-in [VReplication](../../../reference/vreplication/vreplication/) mechanism. This is the preferred strategy in Vitess. +- `gh-ost`: uses 3rd party GitHub's [gh-ost](https://github.com/github/gh-ost) tool. +- `pt-osc`: uses 3rd party Percona's [pt-online-schema-change](https://www.percona.com/doc/percona-toolkit/3.0/pt-online-schema-change.html) as part of [Percona Toolkit](https://www.percona.com/doc/percona-toolkit/3.0/index.html). `pt-osc` strategy is **experimental**. +- `mysql`: managed by the Online DDL scheduler, but executed via normal MySQL statement. Whether it is blocking or not is up to the specific query. +- `direct`: unmanaged. The direct apply of DDL to your database. Whether it is blocking or not is up to the specific query. + +`CREATE` and `DROP` are managed in the same way, by Vitess, whether strategy is `vitess`, `gh-ost` or `pt-osc`. + +See also [ddl_strategy flags](../ddl-strategy-flags). + +## Specifying a DDL strategy + +You will set either `@@ddl_strategy` session variable, or `--ddl_strategy` command line flag. Examples: + +#### Via vtctlclient + +```shell +$ vtctldclient ApplySchema --ddl-strategy "vitess" --sql "ALTER TABLE demo MODIFY id bigint UNSIGNED" commerce +a2994c92_f1d4_11ea_afa3_f875a4d24e90 +``` + +```shell +$ vtctldclient ApplySchema --ddl-strategy "gh-ost --max-load Threads_running=200" --sql "ALTER TABLE demo add column status int" commerce +``` + +#### Via VTGate + +```shell +$ mysql -h 127.0.0.1 -P 15306 commerce +Welcome to the MySQL monitor. Commands end with ; or \g. + +mysql> SET @@ddl_strategy='vitess'; +Query OK, 0 rows affected (0.00 sec) + +mysql> ALTER TABLE demo ADD COLUMN sample INT; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| fa2fb689_f1d5_11ea_859e_f875a4d24e90 | ++--------------------------------------+ +1 row in set (0.00 sec) +``` + +## Choosing a DDL strategy + +Different strategies have different behavior for `ALTER` statements. Sections below first break down specific handling and notes for each strategy, followed by an evaluation of the differences. + +### vitess + +The `vitess` strategy invokes Vitess's built in [VReplication](../../../reference/vreplication/vreplication/) mechanism. It is the mechanism behind resharding, materialized views, imports from external databases, and more. VReplication migrations use the same logic for copying data as do other VReplication operations, and as such the `vitess` strategy is known to be compatible with overall Vitess behavior. VReplication is authored by the maintainers of Vitess. + +VReplication migrations enjoy the general features of VReplication: + +- Seamless integration with Vitess. +- Seamless use of the throttler mechanism. +- Visibility into internal working and status of VReplication. +- Agnostic to planned reparenting and to unplanned failovers. A migration will resume from point of interruption shortly after a new primary is available. + +VReplication migrations further: + +- Are [revertible](../revertible-migrations): you may switch back to the pre-migration schema without losing any data accumulated during and post migration. +- Support a wider range of schema changes. For example, while `gh-ost` has a strict requirement for a shared unique key pre/post migration, `vitess` migrations may work with different keys, making it possible to modify a table's `PRIMARY KEY` without having to rely on an additional `UNIQUE KEY`. + +### gh-ost + +[gh-ost](https://github.com/github/gh-ost) was developed by [GitHub](https://github.com) as a lightweight and safe schema migration tool. + +To be able to run online schema migrations via `gh-ost`: + +- If you're on Linux/amd64 architecture, and on `glibc` `2.3` or similar, there are no further dependencies. Vitess comes with a built-in `gh-ost` binary, that is compatible with your system. Note that the Vitess Docker images use this architecture, and `gh-ost` comes pre-bundled and compatible. +- On other architectures: + - Have `gh-ost` executable installed + - Run `vttablet` with `--gh-ost-path=/full/path/to/gh-ost` flag + +Vitess automatically creates a MySQL account for the migration, with a randomly generated password. The account is destroyed at the end of the migration. + +Vitess takes care of setting up the necessary command line flags. It automatically creates a hooks directory and populates it with hooks that report `gh-ost`'s progress back to Vitess. You may supply additional flags for your migration as part of `@@ddl_strategy` session variable (using `VTGate`) or `--ddl_strategy` command line flag (using `vtctlclient`). Examples: + +- `set @@ddl_strategy='gh-ost --max-load Threads_running=200';` +- `set @@ddl_strategy='gh-ost --max-load Threads_running=200 --critical-load Threads_running=500 --critical-load-hibernate-seconds=60 --default-retries=512';` +- `vtctldclient --ddl-strategy "gh-ost --allow-nullable-unique-key --chunk-size 200" ...` + +**Note:** Do not override the following flags: `alter, database, table, execute, max-lag, force-table-names, serve-socket-file, hooks-path, hooks-hint-token, panic-flag-file`. Overriding any of these may cause Vitess to lose control and track of the migration, or even to migrate the wrong table. + +`gh-ost` throttling is done via Vitess's own tablet throttler, based on replication lag. + +### Using pt-online-schema-change + +[pt-online-schema-change](https://www.percona.com/doc/percona-toolkit/3.0/pt-online-schema-change.html) is part of [Percona Toolkit](https://www.percona.com/doc/percona-toolkit/3.0/index.html), a set of Perl scripts. To be able to use `pt-online-schema-change`, you must have the following setup on all your tablet servers (normally tablets are co-located with MySQL on same host and so this implies setting up on all MySQL servers): + +- `pt-online-schema-change` tool installed and is executable +- Perl `libdbi` and `libdbd-mysql` modules installed. e.g. on Debian/Ubuntu, `sudo apt-get install libdbi-perl libdbd-mysql-perl` +- Run `vttablet` with `-pt-osc-path=/full/path/to/pt-online-schema-change` flag. + +Note that on Vitess Docker images, `pt-online-schema-change` and dependencies are pre-installed. + +Vitess automatically creates a MySQL account for the migration, with a randomly generated password. The account is destroyed at the end of the migration. + +Vitess takes care of supplying the command line flags, the DSN, the username & password. It also sets up `PLUGINS` used to communicate migration progress back to the tablet. You may supply additional flags for your migration as part of `@@ddl_strategy` session variable (using `VTGate`) or `-ddl_strategy` command line flag (using `vtctlclient`). Examples: + +- `set @@ddl_strategy='pt-osc --null-to-not-null';` +- `set @@ddl_strategy='pt-osc --max-load Threads_running=200';` +- `vtctldclient ApplySchema --ddl-strategy "pt-osc --alter-foreign-keys-method auto --chunk-size 200" ...` + +Vitess tracks the state of the `pt-osc` migration. If it fails, Vitess makes sure to drop the migration triggers. Vitess keeps track of the migration even if the tablet itself restarts for any reason. Normally that would terminate the migration; Vitess will cleanup the triggers if so, or will happily let the migration run to completion if not. + +Do not override the following flags: `alter, pid, plugin, dry-run, execute, new-table-name, [no-]drop-new-table, [no-]drop-old-table`. + +`pt-osc` throttling is done via Vitess's own tablet throttler, based on replication lag, and via a `pt-online-schema-change` plugin. + +{{< warning >}} +The integration with `pt-online-schema-change` is **experimental** +{{< /warning >}} + +### Comparing the options + +There are pros and cons to using any of the strategies. Some notable differences: + +#### General + +- All three options mimic an `ALTER TABLE` statement by creating and populating a shadow/ghost table behind the scenes, slowly bringing it up to date, and finally switching between the original and shadow tables. +- All three options utilize the Vitess throttler. + +#### Support + +- VReplication (`vitess` strategy) is internal to Vitess and supported by the Vitess maintainers. +- `gh-ost` enjoys partial, informal support from Vitess maintainers. +- `pt-online-schema-change` is out of the maintainers control. + +#### Setup + +- VReplication is part of Vitess +- A `gh-ost` binary is embedded within the Vitess binary, compatible with `glibc 2.3` and `Linux/amd64`. The user may choose to use their own `gh-ost` binary, configured with `-gh-ost-path`. +- `pt-online-schema-change` is not included in Vitess, and the user needs to set it up on tablet hosts. + - Note that on Vitess Docker images, `pt-online-schema-change` and dependencies _are_ pre-installed. + +#### Load + +- `pt-online-schema-change` uses triggers to propagate changes. This method is traditionally known to generate high load on the server. Both VReplication and `gh-ost` tail the binary logs to capture changes, and this approach is known to be more lightweight. +- When throttled, `pt-online-schema-change` still runs trigger actions, whereas both VReplication and `gh-ost` cease transfer of data (they may keep minimal bookkeeping operations). + +#### Cut-over + +- All strategies use an atomic cut-over based on MySQL locking. At the end of the migration, the tables are switched, and incoming queries are momentarily blocked, but not lost. +- In addition, `vitess` offers a buffering layer, that reduces the contention on the database server at cut-over time. + +#### MySQL compatibility + +- `pt-online-schema-change` partially supports foreign keys. Neither `gh-ost` nor `VReplication` support foreign keys. + +## Vitess functionality comparison + +| Strategy | Managed | Online | Trackable | Declarative | Revertible | Recoverable | +|----------|---------|--------|-----------|-------------|---------------------|-------------| +| `direct` | No | MySQL* | No | No | No | No | +| `mysql` | Yes | MySQL* | Yes | Yes | No | No | +| `pt-osc` | Yes | Yes* | Yes | Yes | `CREATE,DROP` | No* | +| `gh-ost` | Yes | Yes* | Yes+ | Yes | `CREATE,DROP` | No* | +| `vitess` | Yes | Yes* | Yes+ | Yes | `CREATE,DROP,ALTER` | Yes | + +- **Managed**: whether Vitess schedules and operates the migration +- **Online**: + - MySQL supports limited online (`INPLACE`) DDL as well as `INSTANT` DDL. See [support chart](https://dev.mysql.com/doc/refman/8.0/en/innodb-online-ddl-operations.html). `INSTANT` DDL is instant on both primary and replicas. `INPLACE` is non-blocking on parent but serialized on replicas, causing replication lag. Otherwise migrations are blocking on both primary and replicas. + - `gh-ost`, `vitess` do not support foreign keys + - `pt-osc` has support for foreign keys (may apply collateral blocking operations) +- **Trackable**: able to determine migration state (`ready`, `running`, `complete` etc) + - `vitess` and `gh-ost` strategies also makes available _progress %_ and _ETA seconds_ +- **Declarative**: support `--declarative` flag +- **Revertible**: `vitess` strategy supports [revertible](../revertible-migrations/) `ALTER` statements (or `ALTER`s implied by `--declarative` migrations). All managed strategies supports revertible `CREATE` and `DROP`. +- **Recoverable**: a `vitess` migration interrupted by planned/unplanned failover, [automatically resumes](../recoverable-migrations/) work from point of interruption. `gh-ost` and `pt-osc` will not resume after failover, but Vitess will automatically retry the migration (by marking the migration as failed and by initiating a `RETRY`), exactly once for any migration. diff --git a/content/en/docs/19.0/user-guides/schema-changes/ddl-strategy-flags.md b/content/en/docs/19.0/user-guides/schema-changes/ddl-strategy-flags.md new file mode 100644 index 000000000..a950b42c5 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/ddl-strategy-flags.md @@ -0,0 +1,58 @@ +--- +title: ddl_strategy flags +weight: 4 +aliases: ['/docs/user-guides/schema-changes/ddl-strategy-flags/'] +--- + +[`ddl_strategy`](../ddl-strategies) accepts flags in command line format. The flags can be vitess-specific, or, if unrecognized by Vitess, are passed on the underlying online schema change tools. + +## Vitess flags + +Vitess respects the following flags. They can be combined unless specifically indicated otherwise: + +- `--allow-concurrent`: allow a migration to run concurrently to other migrations, rather than queue sequentially. Some restrictions apply, see [concurrent migrations](../concurrent-migrations). +- `--allow-zero-in-date`: normally Vitess operates with a strict `sql_mode`. If you have columns such as `my_datetime DATETIME DEFAULT '0000-00-00 00:00:00'` and you wish to run DDL on these tables, Vitess will prevent the migration due to invalid values. Provide `--allow-zero-in-date` to allow either a fully zero-date or a zero-in-date inyour schema. See also [NO_ZERO_IN_DATE](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_zero_in_date) and [NO_ZERO_DATE](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_zero_date) documentation for [sql_mode](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html). + +- `--analyze-table`: for `ALTER TABLE` operation, and in `online/vitess` strategy, run an `ANALYZE NO_WRITE_TO_BINLOG TABLE` just before starting the migration process, to get better estimation of the number of rows on the migrated table. + +- `cut-over-threshold="`: set an explicit threshold and timeout for a `vitess` `ALTER TABLE` cut-over phase. The default cut-over threshold, if not specified, is `10s`. A `vitess` migration will not attempt to cut-over if the vstream, or replication lag, is more than the cut-over threshold. Also, during cut-over, table locks will timeout after the same cut-over threshold (aborting the operation). + Normal values are in the range `5s`..`30s`. Too low and cut-over may never succeed because of the inherent async nature of `vitess` migrations. Too high and table locks will be placed for too long, effectively rendering the table inaccessible. + +- `--declarative`: mark the migration as declarative. You will define a desired schema state by supplying `CREATE` and `DROP` statements, ad Vitess will infer how to achieve the desired schema. If need be, it will generate an `ALTER` migration to convert to the new schema. See [declarative migrations](../declarative-migrations). + +- `--fast-range-rotation`: when the migration runs on a table partitioned by `RANGE`, and the migration either runs a single `DROP PARTITION` or a single `ADD PARTITION`, and nothing other than that, then this flags instructs Vitess to run the `ALTER TABLE` statement directly against MySQL, as opposed to running an Online DDL with a shadow table. For `DROP PARTITION`, this flag is actually always desired, and will possibly become default/redundant in the future. If all conditions are indeed met, then the migration is not revertible. + +- `--in-order-completion`: a migration that runs with this DDL strategy flag may only complete if no prior migrations are still pending (pending means either `queued`, `ready` or `running` states). `--in-order-completion` considers the order by which migrations were submitted. Note that `--in-order-completion` still allows concurrency. In fact, it is designed to work with concurrent migrations. The idea is that while many migrations may run concurrently, they must _complete_ in-order. + - This lets the user submit multiple migrations which may have some dependencies (for example, introduce two views, one of which reads from the other). As long as the migrations are submitted in a valid order, the user can then expect `vitess` to complete the migrations successfully (and in that order). + - This strategy flag applies to any `CREATE|DROP TABLE|VIEW` statements, and to `ALTER TABLE` with `vitess|online` strategy. + - It _does not_ apply to `ALTER TABLE` when using the `gh-ost`, `pt-osc`, `mysql`, or `direct` strategies. + +- `--postpone-completion`: initiate a migration that will only cut-over per user command, i.e. will not auto-complete. This gives the user control over the time when the schema change takes effect. See [postponed migrations](../postponed-migrations). + + `--declarative` migrations are only evaluated when scheduled to run. If a migrations is both `--declarative` and `--postpone-completion` then it will remain in `queued` state until the user issues a `ALTER VITESS_MIGRATION ... COMPLETE`. If it turns out that Vitess should run the migration as an `ALTER` then it is only at that time that the migration starts. + +- `--postpone-launch`: initiate a migration that remains `queued` and only launches per user command. See [postponed migrations](../postponed-migrations). + +- `--retain-artifacts=`: set an explicit artifact retention for this migration. If nonzero, this value overrides the `vttablet --retain_online_ddl_tables` value. + +- `--singleton`: only allow a single pending migration to be submitted at a time. From the moment the migration is queued, and until either completion, failure or cancellation, no other new `--singleton` migration can be submitted. New requests will be rejected with error. `--singleton` works as a an exclusive lock for pending migrations. Note that this only affects migrations with `--singleton` flag. Migrations running without that flag are unaffected and unblocked. + +- `--singleton-context`: only allow migrations submitted under same _context_ to be pending at any given time. Migrations submitted with a different _context_ are rejected for as long as at least one of the initially submitted migrations is pending. + + It does not make sense to combine `--singleton` and `--singleton-context`. + +## Pass-through flags + +Flags unrecognized by Vitess are passed on to the underlying schema change tools. For example, a `gh-ost` migration can run with: +```sql +set @@ddl_strategy='gh-ost --max-load Threads_running=200' +``` +Since Vitess knows nothing about `--max-load` it will pass it on as a command line argument to `gh-ost`. Consult [gh-ost documentation](https://github.com/github/gh-ost) for supported command line flags. + +Similarly, a `pt-online-schema-change` migration can run with: +```sql +set @@ddl_strategy='pt-osc --null-to-not-null' +``` +Consult [pt-online-schema-change documentation](https://www.percona.com/doc/percona-toolkit/3.0/pt-online-schema-change.html) for supported command line flags. + +The `vitess` strategy (formerly known as `online`) uses Vitess internal mechanisms and is not a standalone command line tool. therefore, it has no particular command line flags. For internal testing/CI purposes, the `vitess` strategy supports `--vreplication-test-suite`, and this flag must **not** be used in production as it can have destructive consequences. diff --git a/content/en/docs/19.0/user-guides/schema-changes/declarative-migrations.md b/content/en/docs/19.0/user-guides/schema-changes/declarative-migrations.md new file mode 100644 index 000000000..3fceb8307 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/declarative-migrations.md @@ -0,0 +1,117 @@ +--- +title: Declarative migrations +weight: 11 +aliases: ['/docs/user-guides/schema-changes/declarative-migrations/'] +--- + +Vitess's [managed schema changes](../managed-online-schema-changes/) offer _declarative_ online schema migrations: + +- The user may indicate a desired table schema and Vitess will make it so, whether the table exists or not, or +- The user may indicate a table should not exist, and Vitess will make it so. + +Declarative DDLs are expressed via: + +- Complete `CREATE TABLE` statement (make the table in desired state) +- `DROP TABLE` statement (make the table go) + +Altering tables in declarative DDL is done by issuing `CREATE TABLE` statements with the desired state. `ALTER` statements are not allowed. + +Declarative DDLs have the property of being idempotent. For example, a user may submit the same `CREATE TABLE` statement _twice_, one after another. If the 1st is successful, then the 2nd is a noop, and considered as implicitly successful. Likewise, two `DROP TABLE` DDLs for same statement will each ensure the table does not exist. If the 1st is successful, then the 2nd has nothing to do and is implicitly successful. + +## Usage + +Add `--declarative` to any of the online DDL strategies. Example: + +```sql + +mysql> set @@ddl_strategy='vitess --declarative'; + +-- The following migration creates a new table: +mysql> create table decl_table(id int primary key); ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| b06475e5_8a74_11eb_badd_f875a4d24e90 | ++--------------------------------------+ + +-- The next migration will implicitly ALTER the table decl_table into desired state: +mysql> create table decl_table(id int primary key, ts timestamp not null); ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| b7d6e6fb_8a74_11eb_badd_f875a4d24e90 | ++--------------------------------------+ + +-- Next migration does not change table structure, hence is a noop and implicitly successful: +mysql> create table decl_table(id int primary key, ts timestamp not null); ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 110574b1_8a75_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +``` + +Consider migration `b7d6e6fb_8a74_11eb_badd_f875a4d24e90` above, which results in an `ALTER`. A look into the migration shows: + +```sql +mysql> show vitess_migrations like 'b7d6e6fb_8a74_11eb_badd_f875a4d24e90'\G +*************************** 1. row *************************** + id: 19 + migration_uuid: b7d6e6fb_8a74_11eb_badd_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: decl_table +migration_statement: create table decl_table ( + id int primary key, + ts timestamp not null +) + strategy: vitess + options: --declarative + added_timestamp: 2021-03-21 20:39:08 +requested_timestamp: 2021-03-21 20:39:07 + ready_timestamp: 2021-03-21 20:39:10 + started_timestamp: 2021-03-21 20:39:10 + liveness_timestamp: 2021-03-21 20:39:13 +completed_timestamp: 2021-03-21 20:39:13 + cleanup_timestamp: NULL + migration_status: complete + log_path: + artifacts: _b7d6e6fb_8a74_11eb_badd_f875a4d24e90_20210321203910_vrepl, + retries: 0 + tablet: zone1-0000000100 + tablet_failure: 0 + progress: 100 + migration_context: vtgate:38368dbe-8a60-11eb-badd-f875a4d24e90 + ddl_action: alter + message: ADD COLUMN `ts` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP + eta_seconds: 0 +``` +Note how while the migration statement is `create`, the migration's `ddl_action` ends up being `alter`, and `message` indicates the alter options. + +You may add `--declarative` even if you otherwise supply flags to your favorite strategy. For example, the following is valid: +```sql +set @@ddl_strategy='gh-ost --declarative --max-load=Threads_running=100'; +``` + +Vitess notes down the `--declarative` flag and does not pass it to `gh-ost`, `pt-osc` or `VReplication`. + +## Implementation details + +The user submits a declarative DDL. Tables schedule the migration to execute, but at time of execution, may modify the migration on the fly and end up running a different migration. + +Consider the following types of migrations: + +- A `REVERT` has no special behavior, it acts as a normal revert. +- `ALTER` is rejected (migration will fail) +- `DROP`: silently mark as successful if the table does not exist. Otherwise treat the DDL as a normal `DROP`. +- `CREATE`: either, + - The table does not exist: proceed as normal `CREATE` + - The table exists: evaluate the SQL diff between the existing table schema and the proposed schema. Either: + - There is no diff (exact same schema): silently mark as successful + - There is a diff: rewrite the DDL as an actual `ALTER`, run using relevant strategy. + +Declarative DDLs are [revertible](../revertible-migrations/). Note: + +- A declarative migration which ends up being an `ALTER` is only revertible if executed with `vitess` strategy. +- A declarative migration which ends up being a noop (and implicitly successful), implies a noop revert. diff --git a/content/en/docs/19.0/user-guides/schema-changes/managed-online-schema-changes.md b/content/en/docs/19.0/user-guides/schema-changes/managed-online-schema-changes.md new file mode 100644 index 000000000..2081b6ef2 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/managed-online-schema-changes.md @@ -0,0 +1,242 @@ +--- +title: Managed, Online Schema Changes +weight: 2 +aliases: ['/docs/user-guides/managed-online-schema-changes/'] +--- + +Vitess offers managed, online schema migrations (aka Online DDL), transparently to the user. Vitess Online DDL offers: + +- Non-blocking migrations +- Migrations are asyncronously auto-scheduled, queued and executed by tablets +- Migration state is trackable +- Migrations are cancellable +- Migrations are retry-able +- Lossless, [revertible migrations](../revertible-migrations/) +- Support for [declarative migrations](../declarative-migrations/) +- Support for [postponed migrations](../postponed-migrations/) +- Support for [failover agnostic migrations](../recoverable-migrations/) +- Support for [concurrent migrations](../concurrent-migrations/) +- See also [advanced usage](../advanced-usage/) + +As general overview: + +- User chooses a [strategy](../ddl-strategies) for online DDL (online DDL is opt in) +- User submits one or more schema change queries, using the standard MySQL `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `CREATE VIEW`, `ALTER VIEW`, `DROP VIEW` syntax. +- Vitess responds with a Job ID for each schema change query. +- Vitess resolves affected shards. +- A shard's `primary` tablet schedules the migration to run when possible. +- Tablets will independently run schema migrations: + - `ALTER TABLE` statements run via `VReplication`, `gh-ost` or `pt-online-schema-change`, as per selected [strategy](../ddl-strategies) + - `CREATE TABLE` and `CREATE VIEW` statements run directly. + - `DROP TABLE` statements run [safely and lazily](https://github.com/vitessio/vitess/blob/main/doc/design-docs/SafeLazyDropTables.md). + - `ALTER VIEW` and `DROP VIEW` are internally modified to allow quick revert. +- Vitess provides the user a mechanism to view migration status, launch (if required), complete (if required), cancel or retry migrations, based on the job ID. + +## Syntax and supported statements + +Online DDL applies to the following statements: + +- `CREATE TABLE` +- `ALTER TABLE` +- `DROP TABLE` +- `CREATE VIEW` +- `ALTER VIEW` +- `DROP VIEW` + +Other DDL statements, such as `RENAME`, `TRUNCATE`, `OPTIMIZE`, etc., are not managed by the Online DDL mechanism and are executed directly on the backend MySQL servers. + +### ALTER TABLE + +Use the standard MySQL `ALTER TABLE` syntax to run online DDL. Whether your schema migration runs synchronously (the default MySQL behavior) or asynchronously (aka online), is determined by `ddl_strategy`. + +We assume we have a keyspace (schema) called `commerce`, with a table called `demo`, that has the following definition: + +```sql +CREATE TABLE `demo` ( + `id` int NOT NULL, + `status` varchar(32) DEFAULT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB +``` + +Consider the following schema migration statement: +```sql +ALTER TABLE demo MODIFY id bigint UNSIGNED; +``` + +This statement can be executed as: + +- a `vitess` (aka `online`), managed online migration +- a `gh-ost`, managed online migration +- a `pt-online-schema-change`, managed online migration (**experimental**) +- a synchronous, [unmanaged schema change](../unmanaged-schema-changes/) + +See [DDL Strategies](../ddl-strategies) for discussion around the different options. + +### CREATE TABLE + +Use the standard MySQL `CREATE TABLE` syntax. The query goes through the same [migration flow](#migration-flow-and-states) as `ALTER TABLE` does. The tablets eventually run the query directly on the MySQL backends. + +### DROP TABLE + +Use the standard MySQL `DROP TABLE` syntax. The query goes through the same [migration flow](#migration-flow-and-states) as `ALTER TABLE` does. Tables are not immediately dropped. Instead, they are renamed into special names. For a while, the operation is revertible, after which the table lifecycle mechanism recognizes that the table is eligible for destruction, to then slowly and safely transition through lifecycle states into finally getting dropped. + +### CREATE VIEW, ALTER VIEW, DROP VIEW + +Use the standard MySQL syntax for these statements. All queries go through the same migration flow as above, and are revertible. Like `DROP TABLE`, a `DROP VIEW` statements does not immediately drop a view, but instead renamed is for safe keeping. + +### Statement transformations + +Vitess may modify your queries to qualify for online DDL statement. Modifications include: + +- A multi-table `DROP` statement is replaced by multiple `DROP` statements, each operating on a single table (and each tracked by its own job ID). +- A `CREATE INDEX` statement is replaced by the equivalent `ALTER TABLE` statement. + +## ddl_strategy + +You will set either `@@ddl_strategy` session variable, or `--ddl_strategy` command line flag, to control your schema migration strategy, and specifically, to enable and configure online DDL. Details in [DDL Strategies](../ddl-strategies). A quick overview: + +- The value `"vitess"` instructs Vitess to run an `ALTER TABLE` online DDL via `VReplication`. This is the preferred method. +- The value `"gh-ost"` instructs Vitess to run an `ALTER TABLE` online DDL via `gh-ost`. +- The value `"pt-osc"` instructs Vitess to run an `ALTER TABLE` online DDL via `pt-online-schema-change`. +- You may specify arguments for your tool of choice, e.g. `"gh-ost --max-load Threads_running=200"`. Details follow. +- The value `"direct"`, means not an online DDL. The empty value (`""`) is also interpreted as `direct`. A query is immediately pushed and applied on backend servers. This is the default strategy. The migration is not managed and is not trackable. + +`CREATE` and `DROP` statements run in the same way for `"vitess"`, `"gh-ost"` and `"pt-osc"` strategies, and we consider them all to be _online_. + +See also [ddl_strategy flags](../ddl-strategy-flags). + +## Running, tracking and controlling Online DDL + +Vitess provides two interfaces to interacting with Online DDL: + +- SQL commands, via `VTGate` +- Command line interface, via `vtctlclient` + +Supported interactions are: + +- [Running migrations](../audit-and-control/#running-migrations) (submitting Online DDL requests) +- [Tracking migrations](../audit-and-control/#tracking-migrations) +- [Launching a migration](../audit-and-control/#launching-a-migration) or all migrations, if explicitly set to postpone launch. +- [Completing a migration](../audit-and-control/#completing-a-migration) or all migrations, if explicitly set to postpone completion. +- [Cancelling a migration](../audit-and-control/#cancelling-a-migration) +- [Cancelling all pending migrations](../audit-and-control/#cancelling-all-keyspace-migrations) +- [Retrying a migration](../audit-and-control/#retrying-a-migration) +- [Reverting a migration](../audit-and-control/#reverting-a-migration) + +See [Audit and Control](../audit-and-control/) for a detailed breakdown. As quick examples: + +#### Executing an Online DDL via VTGate/SQL + +```sql +mysql> set @@ddl_strategy='vitess'; + +mysql> alter table corder add column ts timestamp not null default current_timestamp; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| bf4598ab_8d55_11eb_815f_f875a4d24e90 | ++--------------------------------------+ + +mysql> drop table customer; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 6848c1a4_8d57_11eb_815f_f875a4d24e90 | ++--------------------------------------+ +``` + +#### Executing an Online DDL via vtctlclient/ApplySchema + +```shell +$ vtctldclient ApplySchema --ddl-strategy "vitess" --sql "ALTER TABLE demo MODIFY id bigint UNSIGNED" commerce +a2994c92_f1d4_11ea_afa3_f875a4d24e90 +``` +You my run multiple migrations withing the same `ApplySchema` command: +```shell +$ vtctldclient ApplySchema --ddl-strategy "vitess" --sql "ALTER TABLE demo MODIFY id bigint UNSIGNED; CREATE TABLE sample (id int PRIMARY KEY); DROP TABLE another;" commerce +3091ef2a_4b87_11ec_a827_0a43f95f28a3 +``` + +`ApplySchema` accepts the following flags: + +- `--ddl_strategy`: by default migrations run directly via MySQL standard DDL. This flag must be applied to indicate an online strategy. See also [DDL strategies](../ddl-strategies) and [ddl_strategy flags](../ddl-strategy-flags). +- `-migration_context `: all migrations in a `ApplySchema` command are logically grouped via a unique _context_. A unique value will be supplied automatically. The user may choose to supply their own value, and it's their responsibility to provide with a unique value. Any string format is accepted. + The context can then be used to search for migrations, via `SHOW VITESS_MIGRATIONS LIKE 'the-context'`. It is visible in `SHOW VITESS_MIGRATIONS ...` output as the `migration_context` column. + +## Migration flow and states + +A migration can be in any one of these states: + +- `queued`: a migration is submitted +- `ready`: a migration is picked from the queue to run +- `running`: a migration was started. It is periodically tested to be making progress. +- `complete`: a migration completed successfully +- `failed`: a migration started running and failed due to whatever reason +- `cancelled`: a _pending_ migration was cancelled + +A migration is said to be _pending_ if we expect it to run and complete. Pending migrations are those in `queued`, `ready` and `running` states. + +For more about internals of the scheduler and how migration states are controlled, see [Online DDL Scheduler](https://github.com/vitessio/vitess/blob/main/doc/design-docs/OnlineDDLScheduler.md) + +## Configuration + +- `--retain_online_ddl_tables`: (`vttablet`) determines how long vttablet should keep an old migrated table before purging it. Type: duration. Default: 24 hours. + + Example: `vttablet -retain_online_ddl_tables 48h` + +- `--migration_check_interval`: (`vttablet`) interval between checks for submitted migrations. Type: duration Default: 1 minute. + + Example: `vttablet --migration_check_interval 30s` + +- `--enable_online_ddl`: (`vtgate`) whether Online DDL operations are at all possible through `VTGate`. Type: boolean. Default: `true` + + Example: `vtgate --enable_online_ddl=false` to disable access to Online DDL via `VTGate`. + +## Auto resume after failure + +VReplication based migrations (`ddl_strategy="vitess"`) are [failover agnostic](../recoverable-migrations/). They automatically resume after either planned promotion ([PlannedReparentShard](../../configuration-advanced/reparenting/#plannedreparentshard-planned-reparenting)), emergency promotion ([EmergencyReparentShard](../../configuration-advanced/reparenting/#emergencyreparentshard-emergency-reparenting)) or completely external reparenting. + +Once the new primary is in place and turns active, it auto-resumes the VReplication stream. The online DDL scheduler assumes ownership of the stream and follows it to completion. + +The new primary must be available within `10 minutes`, or else the migration is considered to be stale and is aborted. + +## Auto retry after failure + +Neither `gh-ost` and `pt-osc` are able to resume from point of failure, or after a failover. However, Vitess management can issue an automated retry (starting the migration afresh). + +- which `vttablet` initiated the migration +- how many times a migration has been retried +- whether a migration failed due to a `vttablet` failure (as is the case in a failover scenario) + +Vitess will auto-retry a failed migration when: + +- The migration failed due to a `vttablet` failure, and +- it has not been retried (this is a temporary restriction) + +The migration will be transitioned into `queued` state, as if the user requested a `retry` operation. Note that this takes place on a per-shard basis. + +The primary use case is a primary failure and failover. The newly promoted tablet will be able to retry the migration that broke during the previous primary failure. To clarify, the migration will start anew, as at this time there is no mechanism to resume a broken migration. + + +## Throttling + +All three strategies: `vitess`, `gh-ost` and `pt-osc` utilize the tablet throttler, which is a cooperative throttler service based on replication lag. The tablet throttler automatically detects topology `REPLICA` tablets and adapts to changes in the topology. See [Tablet throttler](../../../reference/features/tablet-throttler/). + +- `vitess` strategy uses the throttler by the fact VReplication natively uses the throttler on both source and target ends (for both reads and writes) +- `gh-ost` uses the throttler via `--throttle-http`, which is automatically provided by Vitess +- `pt-osc` uses the throttler by replication lag plugin, automatically injected by Vitess. + +**NOTE** that at this time (and subject to change) the tablet throttler is disabled by default. Enable it with `vttablet`'s `-enable-lag-throttler` flag. If the tablet throttler is disabled, schema migrations will not throttle on replication lag. + +## Table cleanup + +All `ALTER` strategies leave artifacts behind. Whether successful or failed, either the original table or the _ghost_ table is left still populated at the end of the migration. Vitess explicitly makes sure the tables are not dropped at the end of the migration. This is for two reasons: + +- Make the table/data still available for a while, and +- In MySQL prior to `8.0.23`, a `DROP TABLE` operation can be dangerous in production as it commonly locks the buffer pool for a substantial period. + +The tables are kept for 24 hours after migration completion. Vitess automatically cleans up those tables as soon as a migration completes (either successful or failed). You will normally not need to do anything. + +Artifact tables are identifiable via `artifacts` column in a `SHOW VITESS_MIGRATION ...` command. You should generally not touch these tables. It's possible to `DROP` those tables with `direct` DDL strategy. Note that dropping tables in production can be risky and lock down your database for a substantial period of time. Dropping artifact tables also makes the migrations impossible to [revert](../revertible-migrations/). + diff --git a/content/en/docs/19.0/user-guides/schema-changes/postponed-migrations.md b/content/en/docs/19.0/user-guides/schema-changes/postponed-migrations.md new file mode 100644 index 000000000..0b58644f8 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/postponed-migrations.md @@ -0,0 +1,321 @@ +--- +title: Postponed migrations +weight: 12 +aliases: ['/docs/user-guides/schema-changes/postponed-migrations/'] +--- + +Postponed migrations allow: + +- Postponing the launch of a migration, and/or +- Postponing the final cut-over/completion of a migration. + +In both cases, it takes an explicit user interaction to launch or to complete the migration. + +Normally, migrations are executed by Vitess and are launched and completed automatically. For example, an `ALTER` on a large table can take hours or more to complete. Vitess automatically instates the new schema in place whenever it is satisfied that the `ALTER` is complete. Or, a `DROP` statement could wait in queue while other statements are running, only to actually execute hours later. + +## Postpone launch + +A postponed-launch migration will remain in queued state and will not start executing, until instructed to launch. + +Add `--postpone-launch` to any of the online DDL strategies. Example: + +```sql + +mysql> set @@ddl_strategy='vitess --postpone-launch'; + +-- The migration is tracked, but the ALTER process won't start running. +mysql> alter table mytable add column i int not null; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 9e8a9249_3976_11ed_9442_0a43f95f28a3 | ++--------------------------------------+ +``` + +Migrations executed with `--postpone-launch` are visible on `show vitess_migrations` just as normal. They will present as `queued`. The column `postpone_launch` indicates that the migration will not auto-start: + + +```sql +mysql> show vitess_migrations like '9e8a9249_3976_11ed_9442_0a43f95f28a3' \G +*************************** 1. row *************************** + id: 3 + migration_uuid: 9e8a9249_3976_11ed_9442_0a43f95f28a3 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: mytable + migration_statement: alter table mytable add column i int not null + strategy: vitess + options: --postpone-launch + added_timestamp: 2022-09-21 06:28:34 + requested_timestamp: 2022-09-21 06:28:34 + ready_timestamp: NULL + started_timestamp: NULL + liveness_timestamp: NULL + completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: queued + ... + postpone_launch: 1 +``` + +### Use case + +The use case is specific to multi sharded environments. In some cases, a user may wish to experiment a migration on a single shard: + +- To see how long it takes to run. +- To see what impact it has on production traffic. +- To see what impact the schema change has. + +Postponed launch migrations make it possible to launch a migration on specific shards, while the migration remains `queued` on the rest of the shards. + +{{< warning >}} +Completing a migration on a subset of the shards means different shards will have different schemas. Do not do this when adding/removing columns, because the table on affected shards will be inconsistent with that of unaffected shards. This feature can be useful to experiment with adding/removing (ideally non-unique) indexes. +{{< /warning >}} + +### Launching a postponed migration + +Launching a postponed-launch migration is achieved by the following commands: + +```sql +mysql> alter vitess_migration '9e8a9249_3976_11ed_9442_0a43f95f28a3' launch; +``` + +The above unblocks the specific migration on all shards. The migration will execute at the discretion of the Online DDL executor. + +```sql +mysql> alter vitess_migration '9e8a9249_3976_11ed_9442_0a43f95f28a3' launch vitess_shards '-40,40-80'; +``` + +This variation accepts a comma delimited list of shard names. The migration will only launch on the specified shards. the rest of the shards ignore the command. An empty list of shards lets the command run on all shards. + +```sql +mysql> alter vitess_migration launch all; +``` + +Launches all currently postponed migrations on all shards. + +It is also possible to use `vtctlclient OnlineDDL` commands: + +```shell +$ vtctlclient OnlineDDL commerce launch 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce launch all +``` + +Postponed launch is supported for all migrations. + +## Postpone completion + +A common requirement by engineers is to have more control over the cut-over time. With postponed completion migrations, it is possible to: + +- Invoke a migration that postpones completion +- Manually `COMPLETE` a migration + +This lets an engineer observe the change of schema at a point when they're comfortably at their console and prepared to take action should any issue occur. + +Add `--postpone-completion` to any* (see [supported migrations](#supported-migrations)) of the online DDL strategies. Example: + +```sql + +mysql> set @@ddl_strategy='vitess --postpone-completion'; + +-- The migration is tracked, but the table won't get created +mysql> create table mytable(id int primary key); ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| a1dac193_4b86_11ec_a827_0a43f95f28a3 | ++--------------------------------------+ +``` + +Migrations executed with `--postpone-completion` are visible on `show vitess_migrations` just as normal. They will present either as `queued`, `ready` or `running`, at the scheduler's discretion. But they will not actually make changes to affected tables. The column `postpone_completion` indicates that the migration will not auto-complete: + +```sql +mysql> show vitess_migrations like 'a1dac193_4b86_11ec_a827_0a43f95f28a3' \G + + id: 1 + migration_uuid: a1dac193_4b86_11ec_a827_0a43f95f28a3 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: my_table + migration_statement: create table my_table ( + id int primary key +) + strategy: vitess + options: --postpone-completion --allow-zero-in-date + added_timestamp: 2021-11-22 11:23:35 + requested_timestamp: 0000-00-00 00:00:00 + ready_timestamp: NULL + started_timestamp: NULL + liveness_timestamp: NULL + completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: queued + log_path: + artifacts: + retries: 0 + tablet: zone1-0000000100 + tablet_failure: 0 + progress: 0 + migration_context: vtgate:a1d8c5e0-4b86-11ec-a827-0a43f95f28a3 + ddl_action: create + message: + eta_seconds: -1 + rows_copied: 0 + table_rows: 0 + added_unique_keys: 0 + removed_unique_keys: 0 + log_file: + retain_artifacts_seconds: 86400 + postpone_completion: 1 +``` + +```sql +-- The migration is tracked, will start running when scheduler chooses, but will not cut-over +-- to replace the table with the new schema +mysql> alter table another_table add column ts timestamp not null; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| b7d6e6fb_8a74_11eb_badd_f875a4d24e90 | ++--------------------------------------+ + +*************************** 1. row *************************** + id: 3 + migration_uuid: 3091ef2a_4b87_11ec_a827_0a43f95f28a3 +... + strategy: vitess + options: --postpone-completion + added_timestamp: 2021-11-22 11:27:34 + requested_timestamp: 0000-00-00 00:00:00 + ready_timestamp: 2021-11-22 11:27:35 + started_timestamp: 2021-11-22 11:27:35 + liveness_timestamp: 2021-11-22 11:27:39 + completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: running +... + postpone_completion: 1 +``` + +### Completing a postponed migration + +Completing a postponed-completion migration is achieved by: + +```sql +mysql> alter vitess_migration 'b7d6e6fb_8a74_11eb_badd_f875a4d24e90' complete; +``` + +This command instructs Vitess that the migration should not kept waiting any further. +{{< info >}} +The command serves as a hint. It does not synchronously cut-over the migration. It is possible that the migration is not yet ready to cut-over (e.g. a long running `ALTER` may not be done copying all necessary data) +{{< /info >}} + +After issuing the command, value of `postpone_completion` turns to `0`: + +```sql +mysql> show vitess_migrations like '3091ef2a_4b87_11ec_a827_0a43f95f28a3' \G +*************************** 1. row *************************** + id: 3 + migration_uuid: 3091ef2a_4b87_11ec_a827_0a43f95f28a3 +... + strategy: vitess + options: --postpone-completion + added_timestamp: 2021-11-22 11:27:34 + requested_timestamp: 0000-00-00 00:00:00 + ready_timestamp: 2021-11-22 11:27:35 + started_timestamp: 2021-11-22 11:27:35 + liveness_timestamp: 2021-11-22 11:29:32 + completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: running + ... + postpone_completion: 0 +``` + +In the above the migration is still `running`. The scheduler has not determined yet that it is ready to cut-over. Continuing the example, two seconds later: +```sql +mysql> show vitess_migrations like '3091ef2a_4b87_11ec_a827_0a43f95f28a3' \G +*************************** 1. row *************************** + id: 3 + migration_uuid: 3091ef2a_4b87_11ec_a827_0a43f95f28a3 + ... + strategy: vitess + options: --postpone-completion + added_timestamp: 2021-11-22 11:27:34 + requested_timestamp: 0000-00-00 00:00:00 + ready_timestamp: 2021-11-22 11:27:35 + started_timestamp: 2021-11-22 11:27:35 + liveness_timestamp: 2021-11-22 11:29:32 + completed_timestamp: 2021-11-22 11:29:33 + cleanup_timestamp: NULL + migration_status: complete +... + postpone_completion: 0 +``` + + +It is also possible to use `vtctlclient OnlineDDL` commands: + +```shell +$ vtctlclient OnlineDDL commerce complete 2201058f_f266_11ea_bab4_0242c0a8b007 +$ vtctlclient OnlineDDL commerce complete all +``` + +### Supported migrations + +Postponed completion is supported for: + +- `CREATE` and `DROP` for all online strategies +- `ALTER` migrations in `vitess` (formerly known as `online`) strategy +- `ALTER` migrations in `gh-ost` strategy +- `REVERT` migrations, including cascading `REVERT` operations + +Postponed completion is not supported in: + +- `direct` strategy +- `pt-osc` for `ALTER` migrations + +[declarative migrations](../declarative-migrations) will remain `queued` when `--postpone-migration` is specified, until `alter vitess_migration ... complete` is issued. This is true whether the declarative migration implies an eventual `CREATE`, `DROP` or `ALTER`. + +### Implementation details + +The two strong cases for postponed migrations are `DROP` and long running `ALTER`s. Both carry an amount of risk to production above other migrations. + +Postponed `ALTER` migrations (in `vitess` and `gh-ost` strategies) are actually executed, and begin copying table data as well as track ongoing changes. But as they reach the point where cut-over is agreeable, they stall, and keep waiting until the user issues the `alter vitess_migration ... complete` statement. Assuming the user runs the statement when all data has already been copied, it is typically a matter of seconds until the migration completes and the new schema is instated. + +For `CREATE` and `DROP` statements, there's no such backfill process as with `ALTER`, and the migrations are simply not scheduled, until the user issues the `complete` statement. Once the statement is issued, the migrations still need to be scheduled, and may be possibly delayed by an existing queue of migrations. + +## Mixing postponed launch and completion + +You may use both `--postpone-launch --postpone-completion` for a migration. For example, if you wanted to just see how long it takes to run a migration on a single shard and what impact it makes, but then only cut-over with all other shards, you would: + + +```sql + +mysql> set @@ddl_strategy='vitess --postpone-launch --postpone-completion'; + +-- The migration is tracked, but the ALTER process won't start running. +mysql> alter table mytable add column i int not null; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 9e8a9249_3976_11ed_9442_0a43f95f28a3 | ++--------------------------------------+ + +mysql> alter vitess_migration '9e8a9249_3976_11ed_9442_0a43f95f28a3' launch vitess_shards '-40'; +``` + +You'd then wait until `ready_to_complete` to be `1` for that specific shard, at which time you'll have gathered all your data. You'd then: + +```sql +mysql> alter vitess_migration launch all; +``` + +Next, you'd wait for _all_ shard to reach `ready_to_complete`, at which time you'd cut-over all of them: + + +```sql +mysql> alter vitess_migration complete all; +``` diff --git a/content/en/docs/19.0/user-guides/schema-changes/recoverable-migrations.md b/content/en/docs/19.0/user-guides/schema-changes/recoverable-migrations.md new file mode 100644 index 000000000..2972e2144 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/recoverable-migrations.md @@ -0,0 +1,32 @@ +--- +title: Recoverable, failover agnostic migrations +weight: 13 +aliases: ['/docs/user-guides/schema-changes/recoverable-migrations/'] +--- + +Vitess's [managed schema changes](../managed-online-schema-changes/) offer _failover agnostic_ migrations in `vitess` strategy (VReplication based). + +Normally, schema migrations are coupled with the original MySQL server they operate on. A `gh-ost` or a `pt-online-schema-change`, as well as plain direct migrations, may only complete on the same server where they started. Any form of failover, whether planned or unplanned, either breaks the migration or makes it obsolete. + +`vitess` strategy migrations are agnostic to server promotion. A migration can begin on one `primary` tablet, and complete on another tablet which was promoted as `primary` throughout the migration. In large part this is a direct result of the nature of VReplication. + +`vitess` migrations will auto-survive: + +- A planned failover (via [PlannedReparentShard](../../configuration-advanced/reparenting/#plannedreparentshard-planned-reparenting)) +- An emergency reparent ([EmergencyReparentShard](../../configuration-advanced/reparenting/#emergencyreparentshard-emergency-reparenting)) +- An unexpected external reparent +- As long as no more than `10` minutes pass between failure/demotion of previous `primary` tablet and the promotion of the new `primary` tablet. + +## Behavior and limitations + +Whether by planned operation or an unplanned failure, a `vitess` migration's VReplication stream is interrupted while copying/applying data. VReplication's mechanism persists the state of data transfer transactionally with the transfer itself. Any replica will have a _consistent_ state of the migration, even if that replica lags behind the primary. + +When a replica tablet is promoted as `primary`, it notices the VReplication stream, which is meant to be active and running. It sets up the connections and processes to resume its work. It is possible that some retries will take place as the stream re-evaluates its source of data. + +The [Online DDL Scheduler](https://github.com/vitessio/vitess/blob/main/doc/design-docs/OnlineDDLScheduler.md) detects the running stream, and identifies it as having been created by a different tablet. It assumes ownership of the stream and proceeds to follow its progress till completion. + +The stream must be no more than `10` minutes stale, otherwise the scheduler marks the migration as failed. + +There is no limitation on the number of failovers a `vitess` migration can survive. + +No user action is required. Immediately after promotion/failover the migration will present as making no progress. It is likely to present progress within 1 or 2 minutes after promotion. diff --git a/content/en/docs/19.0/user-guides/schema-changes/revertible-migrations.md b/content/en/docs/19.0/user-guides/schema-changes/revertible-migrations.md new file mode 100644 index 000000000..71959cf0d --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/revertible-migrations.md @@ -0,0 +1,231 @@ +--- +title: Revertible migrations +weight: 14 +aliases: ['/docs/user-guides/schema-changes/revertible-migrations/'] +--- + +Vitess's [managed schema changes](../managed-online-schema-changes/) offer _lossless revert_ for online schema migrations: the user may regret a table migration after completion, and roll back the table's schema to previous state _without loss of data_. + +Revertible migrations supported for: + +- `CREATE TABLE` statements: the _revert_ is to _uncreate_ the table +- `DROP TABLE` statements: the _revert_ is to _reinstate_ the table, populated with data from time of `DROP` +- `ALTER TABLE` statements: supported in `vitess` strategy, the _revert_ is to reapply previous table schema, without losing any data added/modified since migration completion. +- Another `revert` migration. It is possible to revert a _revert_, revert the revert of a _revert_, and so forth. + +## Behavior and limitations + +- A revert is a migration of its own, with a migration UUID, similarly to normal migrations. +- Migrations are only for revertible for `24h` since completion. +- It's only possible to revert the last successful migration on a given table. Illustrated following. + - In the future it may be possible to revert down the stack of completed migrations. + - To clarify, it's possibly to revert multiple migrations, even concurrently, but for each table you may only revert the last successful migration on that table. +- `ALTER` migrations are revertible only in `vitess` strategy. +- If a DDL is a noop, then so is its revert: + - If a table `t` exists, and an online DDL is `CREATE TABLE IF NOT EXISTS t (...)`, then the DDL does nothing, and its revert will do nothing. + - If a table `t` does not exist, and an online DDL is `DROP TABLE IF EXISTS t`, then likewise the DDL does nothing, and its revert does nothing. +- Some `ALTER` reverts are not guaranteed to succeed. Examples: + - An `ALTER` which modifies column `i` from `int` to `bigint`, followed by an `INSERT` that places a value larger than max `int`, cannot be reverted, because Vitess cannot place that new value in the old schema. + - An `ALTER` which removes a `UNIQUE KEY`, followed by an `INSERT` that populates a duplicate value on some column, may not be reverted if that duplicate violates the removed `UNIQUE` constraint. + + Vitess cannot know ahead of time whether a _revert_ is possible or not. + +## REVERT syntax + +Via SQL: + +```sql +REVERT VITESS_MIGRATION '69b17887_8a62_11eb_badd_f875a4d24e90'; +``` + +{{< warning >}} +As of Vitess 12.0 `vtctl OnlineDDL revert` is deprecated. Use the `REVERT VITESS_MIGRATION '...' ` SQL command either via `vtctl ApplySchema` or via `vtgate`. +{{< /warning >}} + +Via `vtctl`: + +``` +$ vtctldclient ApplySchema --ddl-strategy "vitess" --sql "revert vitess_migration '69b17887_8a62_11eb_badd_f875a4d24e90'" commerce +``` + +Both operations return a UUID for the revert migration. The user can track the revert migration to find its state. + +## Usage & walkthrough + +Consider the following annotated flow: +```sql +mysql> set @@ddl_strategy='vitess'; + +mysql> create table t(id int primary key); ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 3837e739_8a60_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +-- Wait until migration is complete + +mysql> alter table t add column ts timestamp not null default current_timestamp; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 6bc591b2_8a60_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +-- Wait until migration is complete + +mysql> show create table t \G +*************************** 1. row *************************** + Table: t +Create Table: CREATE TABLE `t` ( + `id` int(11) NOT NULL, + `ts` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 + +-- it is now possible to revert 6bc591b2_8a60_11eb_badd_f875a4d24e90, because it was the last successful migration on table t. +-- it is not possible to revert 3837e739_8a60_11eb_badd_f875a4d24e90, because while it was successful, it is not the last +-- successful migration to run on table t t. + +mysql> revert vitess_migration '6bc591b2_8a60_11eb_badd_f875a4d24e90'; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| ead67f31_8a60_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +-- Wait until migration is complete + +mysql> show create table t \G +*************************** 1. row *************************** + Table: t +Create Table: CREATE TABLE `t` ( + `id` int(11) NOT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 + +-- It is now possible to revert ead67f31_8a60_11eb_badd_f875a4d24e90 as it is the last successful migration to run on table t. +-- Reverting ead67f31_8a60_11eb_badd_f875a4d24e90 affectively means restoring the changes made by 6bc591b2_8a60_11eb_badd_f875a4d24e90 + +mysql> revert vitess_migration 'ead67f31_8a60_11eb_badd_f875a4d24e90'; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 3b99f686_8a61_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +-- Wait until migration is complete + +mysql> show create table t \G +*************************** 1. row *************************** + Table: t +Create Table: CREATE TABLE `t` ( + `id` int(11) NOT NULL, + `ts` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, + PRIMARY KEY (`id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8 + +-- Let's try an invalid migration: ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 7fbdf1c7_8a61_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +-- This will fail because column `id` already exists. + + id: 11 + migration_uuid: 7fbdf1c7_8a61_11eb_badd_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: t +migration_statement: alter table t add column id bigint + strategy: vitess + options: + added_timestamp: 2021-03-21 18:21:36 +requested_timestamp: 2021-03-21 18:21:32 + ready_timestamp: 2021-03-21 18:21:36 + started_timestamp: 2021-03-21 18:21:36 + liveness_timestamp: 2021-03-21 18:21:36 +completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: failed +... + ddl_action: alter + message: Duplicate column name 'id' (errno 1060) (sqlstate 42S21) during query: ALTER TABLE `_7fbdf1c7_8a61_11eb_badd_f875a4d24e90_20210321182136_vrepl` add column id bigint +... + +-- it is impossible to revert 7fbdf1c7_8a61_11eb_badd_f875a4d24e90 because it failed. + ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| c3dff91a_8a61_11eb_badd_f875a4d24e90 | ++--------------------------------------+ + +mysql> show vitess_migrations like 'c3dff91a_8a61_11eb_badd_f875a4d24e90' \G +*************************** 1. row *************************** + id: 12 + migration_uuid: c3dff91a_8a61_11eb_badd_f875a4d24e90 + keyspace: commerce + shard: 0 + mysql_schema: vt_commerce + mysql_table: +migration_statement: revert 7fbdf1c7_8a61_11eb_badd_f875a4d24e90 + strategy: vitess + options: + added_timestamp: 2021-03-21 18:23:31 +requested_timestamp: 2021-03-21 18:23:26 + ready_timestamp: 2021-03-21 18:23:36 + started_timestamp: NULL + liveness_timestamp: NULL +completed_timestamp: NULL + cleanup_timestamp: NULL + migration_status: failed +... + ddl_action: revert + message: can only revert a migration in a 'complete' state. Migration 7fbdf1c7_8a61_11eb_badd_f875a4d24e90 is in 'failed' state +... + +mysql> insert into t values (1, now()); + +mysql> select * from t; ++----+---------------------+ +| id | ts | ++----+---------------------+ +| 1 | 2021-03-21 18:26:47 | ++----+---------------------+ + +mysql> drop table t; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 69b17887_8a62_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +-- Wait until migration is complete + +mysql> select * from t; +ERROR 1146 (42S02): ... + +mysql> revert vitess_migration '69b17887_8a62_11eb_badd_f875a4d24e90'; ++--------------------------------------+ +| uuid | ++--------------------------------------+ +| 9eb00275_8a62_11eb_badd_f875a4d24e90 | ++--------------------------------------+ +-- Wait until migration is complete +-- `t` was not really dropped, but renamed away. This REVERT reinstates it. + +mysql> select * from t; ++----+---------------------+ +| id | ts | ++----+---------------------+ +| 1 | 2021-03-21 18:26:47 | ++----+---------------------+ +``` + +## Implementation details + +Revert for `CREATE` and `DROP` are implemented similarly for all online strategies. + +- The revert for a `CREATE` DDL is to rename the table away and into a [table lifecycle](../table-lifecycle/) name, rather than actually `DROP` it. This keeps th etale safe for a period of time, and makes it possible to reinstate the table, populated with all data, via a 2nd revert. +- The revert for a `DROP` relies on the fact that Online DDL `DROP TABLE` does not, in fact, drop the table, but actually rename it away. Thus, reverting the `DROP` is merely a `RENAME` back into its original place. +- The revert for `ALTER` is only available for `vitess` strategy (formerly called `online`), implemented by `VReplication`. VReplication keep track of a DDL migration by writing down the GTID position through the migration flow. In particular, at time of cut-over and when tables are swapped, VReplication notes the _final_ GTID pos for the migration. + When a revert is requested, Vitess computes a new VReplication rule/filter for the new stream. It them copies the _final_ GTID pos from the reverted migration, and instructs VReplication to resume from that point. + As result, a revert for an `ALTER` migration only needs to catch up with the changelog (binary log entries) since the cut-over of the original migration. To elaborate, it does not need to copy table data, and only needs to consider events for the specific table affected by the revert. This makes the revert operation efficient. diff --git a/content/en/docs/19.0/user-guides/schema-changes/table-lifecycle.md b/content/en/docs/19.0/user-guides/schema-changes/table-lifecycle.md new file mode 100644 index 000000000..dab161895 --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/table-lifecycle.md @@ -0,0 +1,91 @@ +--- +title: Table lifecycle +weight: 5 +aliases: ['/docs/user-guides/table-lifecycle/','/docs/reference/table-lifecycle/', 'docs/reference/features/table-lifecycle/'] +--- + +Vitess manages a table lifecycle flow, an abstraction and automation for a `DROP TABLE` operation. + +## Problems with DROP TABLE + +Vitess inherits the same issues that MySQL has with `DROP TABLE`. Doing a direct +`DROP TABLE my_table` in production can be a risky operation. In busy environments +this can lead to a complete lockdown of the database for the duration of seconds, +to minutes and more. This is typically less of a problem in Vitess than it might +be in normal MySQL, if you are keeping your shard instances (and thus shard +table instances) small, but could still be a problem. + +{{< info >}}MySQL 8.0.23 addresses the issues of DROP TABLE. Vitess changes its course of action based on the MySQL version, see below.{{< /info >}} + + +There are two locking aspects to dropping tables: + +- Purging dropped table's pages from the InnoDB buffer pool(s) +- Removing table's data file (`.ibd`) from the filesystem. + +The exact locking behavior and duration can vary depending on +various factors: + +- Which filesystem is used. +- Whether the MySQL adaptive hash index is used. +- Whether you are attempting to hack around some of the MySQL `DROP TABLE` + performance problems using hard links. + +It is common practice to avoid direct `DROP TABLE` statements and to follow +a more elaborate table lifecycle. + +## Vitess table lifecycle + +The lifecycle offered by Vitess consists of the following stages or some subset of them: + +> _in use_ -> hold -> purge -> evac -> drop -> _removed_ + +To understand the flow better, consider the following breakdown: + +- _In use_: the table is serving traffic, like a normal table. +- `hold`: the table is renamed to some arbitrary new name. The application cannot see it, and considers it as gone. However, the table still exists, with all of its data intact. It is possible to reinstate it (e.g. in case we realize some application still requires it) by renaming it back to its original name. +- `purge`: the table is in the process of being purged (i.e. rows are being deleted). The purge process completes when the table is completely empty. At the end of the purge process the table no longer has any pages in the buffer pool(s). However, the purge process itself loads the table pages to cache in order to delete rows. + Vitess purges the table a few rows at a time, and uses a throttling mechanism to reduce load. + Vitess disables binary logging for the purge. The deletes are not written to the binary logs and are not replicated. This reduces load from disk IO, network, and replication lag. Data is not purged on the replicas. + Experience shows that dropping a table populated with data on a replica has lower performance impact than on the primary, and the tradeoff is worthwhile. +- `evac`: a waiting period during which we expect normal production traffic to slowly evacuate the (now inactive) table's pages from the buffer pool. Vitess hard codes this period for `72` hours. The time is heuristic, there is no tracking of table pages in the buffer pool. +- `drop`: an actual `DROP TABLE` is imminent +- _removed_: table is dropped. When using InnoDB and `innodb_file_per_table` this means the `.ibd` data file backing the table is removed, and disk space is reclaimed. + +## Lifecycle subsets and configuration + +Different environments and users have different requirements and workflows. For example: + +- Some wish to immediately start purging the table, wait for pages to evacuate, then drop it. +- Some want to keep the table's data for a few days, then directly drop it. +- Some just wish to directly drop the table, they see no locking issues (e.g. smaller table). + +Vitess supports all subsets via `--table_gc_lifecycle` flag to `vttablet`. The default is `"hold,purge,evac,drop"` (the complete cycle). Users may configure any subset, e.g. `"purge,drop"`, `"hold,drop"`, `"hold,evac,drop"` or even just `"drop"`. + +Vitess will always work the steps in this order: `hold -> purge -> evac -> drop`. For example, setting `--table_gc_lifecycle "drop,hold"` still first _holds_, then _drops_ + +All subsets end with a `drop`, even if not explicitly mentioned. Thus, `"purge"` is interpreted as `"purge,drop"`. + +In MySQL **8.0.23** and later, table drops do not acquire locks on the InnoDB buffer pool, and are non-blocking for queries that do not reference the table being dropped. Vitess automatically identifies whether the underlying MySQL server is at that version or later and will: + +- Implicitly skip the `purge` stage, even if defined +- Implicitly skip the `evac` stage, even if defined + +## Stateless flow by table name hints + +Vitess does not track the state of the table lifecycle. The process is stateless thanks to an encoding scheme in the table names. Examples: + +- The table `_vt_HOLD_6ace8bcef73211ea87e9f875a4d24e90_20210915120000` is held until `2021-09-15 12:00:00`. The data remains intact. +- The table `_vt_PURGE_6ace8bcef73211ea87e9f875a4d24e90_20210915123000` is at the state where it is being purged, or queued to be purged. Once it's fully purged (zero rows remain), it transitions to the next stage. +- The table `_vt_EVAC_6ace8bcef73211ea87e9f875a4d24e90_20210918093000` is held until `2021-09-18 09:30:00` +- The table `_vt_DROP_6ace8bcef73211ea87e9f875a4d24e90_20210921170000` is eligible to be dropped on `2021-09-21 17:00:00` + +## Automated lifecycle + +Vitess internally uses the above table lifecycle for [online, managed schema migrations](../../../user-guides/schema-changes/managed-online-schema-changes/). All online strategies: `vitess`, `gh-ost`, and `pt-online-schema-change`, create artifact tables or end with leftover tables: Vitess automatically collects those tables. The artifact or leftover tables are immediate moved to `hold` state. Depending on `--table_gc_lifecycle`, they may spend time in this state, getting purged, or immediately transitioned to the next state. + +## User-facing DROP TABLE lifecycle + +When using an online `ddl_strategy`, a `DROP TABLE` is a [managed schema migration](../../../user-guides/schema-changes/managed-online-schema-changes/). It is internally replaced by a `RENAME TABLE` statement, renaming it into a `HOLD` state (e.g. `_vt_HOLD_6ace8bcef73211ea87e9f875a4d24e90_20210915120000`). It will then participate in the table lifecycle mechanism. If `table_gc_lifecycle` does not include the `hold` state, the table proceeds to transition to next included state. + +A multi-table `DROP TABLE` statement is converted to multiple single-table `DROP TABLE` statements, each to then convert to a `RENAME TABLE` statement. diff --git a/content/en/docs/19.0/user-guides/schema-changes/unmanaged-schema-changes.md b/content/en/docs/19.0/user-guides/schema-changes/unmanaged-schema-changes.md new file mode 100644 index 000000000..6a28f8cbc --- /dev/null +++ b/content/en/docs/19.0/user-guides/schema-changes/unmanaged-schema-changes.md @@ -0,0 +1,92 @@ +--- +title: Unmanaged Schema Changes +weight: 1 +aliases: ['/docs/user-guides/operating-vitess/making-schema-changes', '/docs/schema-management/unmanaged-schema-changes/', '/docs/user-guides/unmanaged-schema-changes/'] +--- + +Vitess offers multiple approaches to running unmanaged schema changes. Below, we review each of these approaches. + +We assume we have a keyspace (schema) called `commerce`, with a table called `demo`, that has the following definition: + +```sql +CREATE TABLE `demo` ( + `id` int NOT NULL, + `status` varchar(32) DEFAULT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB +``` + +## ApplySchema + +`ApplySchema` is a `vtctlclient` command that can be used to apply a schema change to a keyspace. The main advantage of using this tool is that it performs some sanity checks about the schema before applying it. However, a downside is that it can be a little too strict and may not work for all use cases. + +Consider the following examples: + +```shell +$ vtctldclient ApplySchema --sql "ALTER TABLE demo modify id bigint unsigned" commerce +``` +```sql +SHOW CREATE TABLE demo; + + +CREATE TABLE `demo` ( + `id` bigint unsigned NOT NULL, + `status` varchar(32) DEFAULT NULL, + PRIMARY KEY (`id`) +) ENGINE=InnoDB +``` +In the above, we run a direct, synchronous, blocking `ALTER TABLE` statement. Knowing the table is in `commerce` keyspace, Vitess autodetects the relevant shards, and then autodetects which is the `primary` server in each shard. It then directly invokes the `ALTER TABLE` statement on all shards (concurrently), and the `vtctlclient` command only returns when all are complete. + + +When applying a new schema, where all statements are `CREATE TABLE` or `CREATE VIEW`, you may supply the flag `--batch-size=`. For example: + +```shell +$ vtctldclient ApplySchema --sql-file /tmp/create.sql --batch-size=100 commerce +``` + +This flag only applies for unmanaged schema changes, and optimizes total run time by sending batches of `CREATE` statements to the underlying databases. + + +## VTGate + +You may run DDL directly from VTGate just like you would send to a MySQL instance. For example: + +```shell +$ mysql -h 127.0.0.1 -P 15306 commerce +Welcome to the MySQL monitor. Commands end with ; or \g. + +mysql> ALTER TABLE demo ADD COLUMN sample INT; +Query OK, 0 rows affected (0.04 sec) +``` + +Just like in the previous example, Vitess will find out what the affected shards are, what the identity is of each shard's `primary`, then invoke the statement on all shards. + +You may apply the change to specific shards by connecting directly to those shards: + +```shell +$ mysql -h 127.0.0.1 -P 15306 commerce/-80 +Welcome to the MySQL monitor. Commands end with ; or \g. + +mysql> ALTER TABLE demo ADD COLUMN sample INT; +Query OK, 0 rows affected (0.04 sec) +``` + +In the above we connect to VTGate via the `mysql` command line client, but of course you may connect with any standard MySQL client or from your application. + +Please do note that if VTGate does not recognize a DDL syntax, the statement will get rejected and that this approach is not recommended for changing large tables. + +## Directly to MySQL + +You can apply schema changes directly to the underlying MySQL shard primary instances. + +VTTablet will eventually notice the change and update itself. This is controlled by the `--queryserver-config-schema-reload-time` parameter which defaults to 1800 seconds. + +You can also explicitly issue the `vtctlclient` `ReloadSchema` command to make it reload immediately. Specify a tablet to reload the schema from, as in: + +```shell +$ vtctlclient ReloadSchema zone1-0000000100 +``` + +Users will likely want to deploy schema changes via `gh-ost` or `pt-online-schema-change`, which do not block the table. Vitess offers [managed, online schema changes](../managed-online-schema-changes/) where it automates the invocation and execution of these tools. Using these schema +deployment tools can be a better approach for large tables, because they should incur no downtime. + diff --git a/content/en/docs/19.0/user-guides/sql/_index.md b/content/en/docs/19.0/user-guides/sql/_index.md new file mode 100644 index 000000000..67307d95a --- /dev/null +++ b/content/en/docs/19.0/user-guides/sql/_index.md @@ -0,0 +1,5 @@ +--- +title: SQL Statement Analysis +description: User guides covering analyzing SQL statements +weight: 4 +--- diff --git a/content/en/docs/19.0/user-guides/sql/vexplain.md b/content/en/docs/19.0/user-guides/sql/vexplain.md new file mode 100644 index 000000000..a677d5da1 --- /dev/null +++ b/content/en/docs/19.0/user-guides/sql/vexplain.md @@ -0,0 +1,253 @@ +--- +title: Analyzing a SQL statement using VEXPLAIN +weight: 1 +aliases: ['/docs/user-guides/vtexplain/'] +--- + +# Introduction + +To see which queries are run on your behalf on the MySQL instances when you execute a query on vtgate, you can use `vexplain [ALL|PLAN|QUERIES]`. + +# `QUERIES` Type + +The `QUERIES` format returns an output similar to what the command line application [`vtexplain`](../../../reference/programs/vtexplain) returns - a list of the queries that have been run on MySQL, and against which shards they were issued. + +## How it works + +Unlike normal `EXPLAIN` queries, `VEXPLAIN QUERIES` actually runs your query, and logs the interactions with the tablets. +After running your query using this extra logging, the result you get is a table with all the interactions listed. + +## How to read the output + +The output has four columns: +* The first column, `#` groups queries that were sent in a single call together. +* Keyspace - which keyspace was this query sent to. +* Shard - for sharded keyspaces, this column will show which shard a query is sent to. +* Query - the actual query used. + +### Example 1: +```mysql +mysql> vexplain queries select * from user where id = 4; ++------+----------+-------+-----------------------------------------------------------+ +| # | keyspace | shard | query | ++------+----------+-------+-----------------------------------------------------------+ +| 0 | ks | c0- | select id, lookup, lookup_unique from `user` where id = 4 | ++------+----------+-------+-----------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +Here we have a query where the planner can immediately see which shard to send the query to. + +### Example 2: +```mysql +mysql> vexplain queries select * from user where lookup = 'apa'; ++------+----------+-------+-------------------------------------------------------------------+ +| # | keyspace | shard | query | ++------+----------+-------+-------------------------------------------------------------------+ +| 0 | ks | -40 | select lookup, keyspace_id from lookup where lookup in ('apa') | +| 1 | ks | c0- | select id, lookup, lookup_unique from `user` where lookup = 'apa' | +| 2 | ks | 40-80 | select id, lookup, lookup_unique from `user` where lookup = 'apa' | ++------+----------+-------+-------------------------------------------------------------------+ +3 rows in set (0.02 sec) +``` + +This is a query where the planner has to do a vindex lookup to find which shard the data might live on. + +# `PLAN` Type + +The `PLAN` format returns the vtgate plan for the given query. +It does so without actually running any queries - it just plans the given query and presents the plan. + +## How to read the output + +The output contains a scalar output having a JSON description of the plan that vtgate will use for the query. + +### Example: +```mysql +mysql> vexplain plan select * from corder join commerce.product as prod on corder.sku = prod.sku; +``` + +```json +{ + "OperatorType": "Join", + "Variant": "Join", + "JoinColumnIndexes": "L:1,L:2,L:3,L:4,R:0,R:1,R:2", + "JoinVars": { + "corder_sku": 0 + }, + "TableName": "corder_product", + "Inputs": [ + { + "OperatorType": "Route", + "Variant": "Scatter", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select corder.sku, corder.order_id as order_id, corder.customer_id as customer_id, corder.sku as sku, corder.price as price from corder where 1 != 1", + "Query": "select corder.sku, corder.order_id as order_id, corder.customer_id as customer_id, corder.sku as sku, corder.price as price from corder", + "Table": "corder" + }, + { + "OperatorType": "Route", + "Variant": "Unsharded", + "Keyspace": { + "Name": "commerce", + "Sharded": false + }, + "FieldQuery": "select prod.sku as sku, prod.description as description, prod.price as price from product as prod where 1 != 1", + "Query": "select prod.sku as sku, prod.description as description, prod.price as price from product as prod where prod.sku = :corder_sku", + "Table": "product" + } + ] +} +``` + +In this example, we are executing a cross-keyspace join between two tables. The `corder` table living in the `customer` keyspace and `product` table living in the `commerce` keyspace. + +# `ALL` Type + +The `ALL` format returns the vtgate plan along with the MySQL explain output for the executed queries. + +## How to read the output + +The output contains a scalar output having a JSON description of the plan that vtgate will use for the query annotated with the explain output from mysql for these queries. + +### Example: + +```mysql +mysql> vexplain all select * from corder join commerce.product as prod on corder.sku = prod.sku; +``` + +```json +{ + "OperatorType": "Join", + "Variant": "Join", + "JoinColumnIndexes": "L:1,L:2,L:3,L:4,R:0,R:1,R:2", + "JoinVars": { + "corder_sku": 0 + }, + "TableName": "corder_product", + "Inputs": [ + { + "OperatorType": "Route", + "Variant": "Scatter", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select corder.sku, corder.order_id as order_id, corder.customer_id as customer_id, corder.sku as sku, corder.price as price from corder where 1 != 1", + "Query": "select corder.sku, corder.order_id as order_id, corder.customer_id as customer_id, corder.sku as sku, corder.price as price from corder", + "Table": "corder", + "mysql_explain_json": { + "query_block": { + "select_id": 1, + "cost_info": { + "query_cost": "0.65" + }, + "table": { + "table_name": "corder", + "access_type": "ALL", + "rows_examined_per_scan": 4, + "rows_produced_per_join": 4, + "filtered": "100.00", + "cost_info": { + "read_cost": "0.25", + "eval_cost": "0.40", + "prefix_cost": "0.65", + "data_read_per_join": "640" + }, + "used_columns": [ + "order_id", + "customer_id", + "sku", + "price" + ] + } + } + } + }, + { + "OperatorType": "Route", + "Variant": "Unsharded", + "Keyspace": { + "Name": "commerce", + "Sharded": false + }, + "FieldQuery": "select prod.sku as sku, prod.description as description, prod.price as price from product as prod where 1 != 1", + "Query": "select prod.sku as sku, prod.description as description, prod.price as price from product as prod where prod.sku = :corder_sku", + "Table": "product", + "mysql_explain_json": { + "query_block": { + "select_id": 1, + "cost_info": { + "query_cost": "1.00" + }, + "table": { + "table_name": "prod", + "access_type": "const", + "possible_keys": [ + "PRIMARY" + ], + "key": "PRIMARY", + "used_key_parts": [ + "sku" + ], + "key_length": "130", + "ref": [ + "const" + ], + "rows_examined_per_scan": 1, + "rows_produced_per_join": 1, + "filtered": "100.00", + "cost_info": { + "read_cost": "0.00", + "eval_cost": "0.10", + "prefix_cost": "0.00", + "data_read_per_join": "272" + }, + "used_columns": [ + "sku", + "description", + "price" + ] + } + } + } + } + ] +} +``` + +This example uses the same query as the previous ones. For all the Route operators, we are annotating them with the MySQL explain output for the query that the route is executing. + +# Safety for DML + +The normal behaviour for `VEXPLAIN` is to not actually run the query for DMLs — it usually only plans the query and presents the produced plan for the `PLAN` type. +Since `vexplain ALL|QUERIES` really runs your queries, you need to add a query directive to show that you are aware that your DML will actually run. + +### Example: + +```mysql +mysql> vexplain queries insert into customer(email) values('abc@xyz.com'); +ERROR 1105 (HY000): VT09008: vexplain queries/all will actually run queries +``` + +This is the error you will get is you do not add the comment directive to your `VEXPLAIN` statement. + +### Example: + +```mysql +mysql> vexplain /*vt+ EXECUTE_DML_QUERIES */ queries insert into customer(email) values('abc@xyz.com'); ++------+----------+-------+-----------------------------------------------------------------------+ +| # | keyspace | shard | query | ++------+----------+-------+-----------------------------------------------------------------------+ +| 0 | customer | 80- | insert into customer(email, customer_id) values ('abc@xyz.com', 1001) | ++------+----------+-------+-----------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +Here we can see how vtgate will insert rows to the main table, but also to the two lookup vindexes declared for this table. + +Note - MySQL client by default strips out the comments from the queries before it sends to the server. +So you'll need to run the client with `-c` flag to allow passing in comments. diff --git a/content/en/docs/19.0/user-guides/sql/vtexplain-in-bulk.md b/content/en/docs/19.0/user-guides/sql/vtexplain-in-bulk.md new file mode 100644 index 000000000..d4ea29475 --- /dev/null +++ b/content/en/docs/19.0/user-guides/sql/vtexplain-in-bulk.md @@ -0,0 +1,217 @@ +--- +title: Analyzing SQL statements in bulk using VTEXPLAIN +weight: 2 +aliases: ['/docs/user-guides/vtexplain-in-bulk/'] +--- + +# Introduction + +This document covers the way the [VTexplain tool](../../../reference/programs/vtexplain) can be used to evaluate if Vitess is compatible with a list of SQL statements. Enabling the evaluation of if queries from an existing application that accesses a MySQL database are generally Vitess-compatible. If there are any issues identified they can be used to target any necessary application changes needed for a successful migration from MySQL to Vitess. + +## Prerequisites + +You can find a prebuilt binary version of the VTexplain tool in [the most recent release of Vitess](https://github.com/vitessio/vitess/releases/). + +You can also build the `vtexplain` binary in your environment. To build this binary, refer to the [build guide](/docs/contributing) for your OS. + +## Overview + +To analyze multiple SQL queries and determine how, or if, Vitess executes each statement, follow these steps: + +1. Gather the queries from your current MySQL database environment +1. Filter out specific queries +1. Populate fake values for your queries +1. Run the VTexplain tool via a script +1. Add your SQL schema +1. Add your VSchema to the output file +1. Run the VTexplain tool and capture the output +1. Check your output for errors + +## 1. Gather the queries from your current MySQL database environment + +These queries should be most, if not all, of the queries that are sent to your current MySQL database over an extended period of time. You may need to record your queries for days or weeks depending on the nature of your application(s) and workload. You will need to normalize the queries you will be analyzing. Depending on the scope and complexity of your applications you may have a few hundred to thousands of distinct normalized queries. To obtain normalized queries you can use common MySQL monitoring tools like VividCortex, Monyog or PMM. + +It is also possible to use the MySQL [general query log](https://dev.mysql.com/doc/refman/8.0/en/query-log.html) feature to capture raw queries and then normalize it using post-processing. + +## 2. Filter out specific queries + +Remove from your list any unsupported queries or queries from non-application sources. The following are examples of queries to remove are: + +* `LOCK/UNLOCK TABLES` - These likely come from schema management tools, which VTGate obviates. +* `FLUSH/PURGE LOGS` - Vitess performs its own log management. +* `performance_schema queries` - These queries are not supported by Vitess. +* `BEGIN/COMMIT` - Vitess supports these statements, but VTexplain does not. + +The following is an example pipeline to filter out these specific queries: +```shell +cat queries.txt \ + | grep -v performance_schema \ + | grep -v information_schema \ + | grep -v @@ \ + | grep -v "SELECT ? $" \ + | grep -v "PURGE BINARY" \ + | grep -v "^SET" \ + | grep -v "^EXPLAIN" \ + | grep -v ^query \ + | grep -v ^BEGIN \ + | grep -v ^COMMIT \ + | grep -v ^FLUSH \ + | grep -v ^LOCK \ + | grep -v ^UNLOCK \ + | grep -v mysql > queries_for_vtexplain.txt +``` + +## 3. Populate fake values for your queries + +Once the queries are normalized in prepared statement style, populate fake values to allow VTexplain to run properly. This is because `vtexplain` operates only on concrete (or un-normalized) queries. Doing this by textual substitution is shown below and typically requires some trial and error. An alternative is to use a MySQL monitoring tool. This tool sometimes has a feature where it can provide one concrete query example for every normalized query form, which is ideal for this purpose. + +If you need to use textual substitution to obtain your concrete queries, the following is an example pipeline you can run: + +```shell +cat queries.txt \ + | perl -p -e 's#\? = \?#1 = 1#g' \ + | perl -p -e 's#= \?#="1"#g' \ + | perl -p -e 's#LIMIT \?#LIMIT 1#g' \ + | perl -p -e 's#\> \?#> "1"#g' \ + | perl -p -e 's#IN \(\?\)#IN (1)#g' \ + | perl -p -e 's#\? AS ONE#1 AS ONE#g' \ + | perl -p -e 's#BINARY \?#BINARY \"1\"#g' \ + | perl -p -e 's#\< \?#< "2"#g' \ + | perl -p -e 's#, \?#, "1"#g' \ + | perl -p -e 's#VALUES \(...\)#VALUES \(1,2\)#g' \ + | perl -p -e 's#IN \(\.\.\.\)#IN \(1,2\)#g' \ + | perl -p -e 's#\- \? #\- 50 #g' \ + | perl -p -e 's#BETWEEN \? AND \?#BETWEEN 1 AND 10#g' \ + | perl -p -e 's#LIKE \? #LIKE \"1\" #g' \ + | perl -p -e 's#OFFSET \?#OFFSET 1#g' \ + | perl -p -e 's#\?, \.\.\.#\"1\", \"2\"#g' \ + | perl -p -e 's#\/ \? #\/ \"1\" #g' \ + | perl -p -e 's#THEN \? ELSE \?#THEN \"2\" ELSE \"3\"#g' \ + | perl -p -e 's#THEN \? WHEN#THEN \"4\" WHEN#g' \ + | perl -p -e 's#SELECT \? FROM#SELECT \"6\" FROM#g' \ + | perl -p -e 's#SELECT \? AS#SELECT id AS#g' \ + | perl -p -e 's#\`DAYOFYEAR\` \(\?\)#DAYOFYEAR \("2020-01-20"\)#g' \ + | perl -p -e 's#YEAR \(\?\)#YEAR \("2020-01-01"\)#g' \ + | grep -v mysql > queries_for_vtexplain.txt + ``` + +## 4. Run the VTexplain tool via a script + +In order to analyze every query in your list, create and run a script. The following is an example Python script that assumes a sharded database with 4 shards. You can adjust this script to match your individual requirements. + +```shell +$ cat testfull.py +for line in open("queries_for_vtexplain.txt", "r").readlines(): + sql = line.strip() + print("vtexplain --schema-file schema.sql --vschema-file vschema.json --shards 4 --sql '%s'" % sql) +x +$ python testfull.py > run_vtexplain.sh +``` + +An alternative method is to use the `--sql-file` option for `vtexplain` to pass the whole file to a single vtexplain invocation. This is much more efficient, but we have found that it can be easier to find errors if you perform one `vtexplain` invocation per SQL query. + +If you choose to use the single invocation, it would look something like: + +```shell +$ vtexplain --schema-file schema.sql --vschema-file vschema.json --shards 4 --sql-file queries_for_vtexplain.txt +``` + +## 5. Add your SQL schema to the output file + +Add your proposed SQL schema to the file created by the script (e.g. schema.sql). The following is an example SQL schema: + +```shell +$ cat schema.sql +CREATE TABLE `user` ( + `user_id` bigint(20) NOT NULL, + `name` varchar(128) DEFAULT NULL, + `balance` decimal(13,4) DEFAULT NULL, + PRIMARY KEY (`user_id`), + KEY `balance` (`balance`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +``` + +## 6. Add your VSchema + +Add your VSchema to the file created by the script: in this example, the file is named `schema.json`. The following is an example VSchema to match the example SQL schema above. + +```shell +$ cat vschema.json +{ + "ks1": { + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "user": { + "column_vindexes": [ + { + "column": "user_id", + "name": "hash" + } + ] + } + } + } +} +``` +Note that unlike the VSchema used in Vitess, e.g. in `vtctldclient GetVSchema` and `vtctldclient ApplyVSchema`, the format required by `vtexplain` differs slightly. There is an extra level of JSON objects at the top-level of the JSON format to allow you to have a single file that represents the VSchema for multiple Vitess keyspaces. In the above example, there is just a single keyspace called `ks1`. + +## 7. Run the VTexplain tool and capture the output + +This step will generate the output you need to analyze to determine what queries may have issues with your proposed VSchema. It may take a long time to finish if you have a number of queries. + +```shell +$ sh -x run_vtexplain.sh 2> vtexplain.output +``` + +## 8. Check your output + +Once you have your full output in vtexplain.output, use `grep` to search for the string "ERROR" to review any issues that VTExplain found. + +### Example: Scattered across shards + +In the following example, VTGate scatters the example query across both shards, and then aggregates the query results. + +```shell +$ vtexplain --schema-file schema.sql --vschema-file vschema.json --shards 4 --sql 'SELECT * FROM user;' +---------------------------------------------------------------------- +SELECT * FROM user + +1 ks1/-40: SELECT * FROM user limit 10001 +1 ks1/40-80: SELECT * FROM user limit 10001 +1 ks1/80-c0: SELECT * FROM user limit 10001 +1 ks1/c0-: SELECT * FROM user limit 10001 +---------------------------------------------------------------------- +``` + +This is not an error, but illustrates a few things about the query: + + * The query of this type will be scattered across all 4 the shards, given the schema and VSchema. + * The phases of the scatter operation will occur in parallel. This is because the number `1` on the left-hand-side of the output indicates the ordering of the operations in time. The same number indicates parallel processing. + * The implicit Vitess row limit of 10000 rows is also seen, even though that was not present in the original query. + +### Example: Query returns an error + +The following query produces an error because Vitess does not support the `AVG` function for scatter queries across multiple shards. + +```shell +$ vtexplain --schema-file schema.sql --vschema-file vschema.json --shards 4 --sql 'SELECT AVG(balance) FROM user;' +ERROR: vtexplain execute error in 'SELECT AVG(balance) FROM user': unsupported: in scatter query: complex aggregate expression +``` + +### Example: Targeting a single shard + +The following query only targets a single shard because the query supplies the sharding key. + +```shell +$ vtexplain --schema-file schema.sql --vschema-file vschema.json --shards 2 --sql 'SELECT * FROM user WHERE user_id = 100;' +---------------------------------------------------------------------- +SELECT * FROM user WHERE user_id = 100 + +1 ks1/80-c0: SELECT * FROM user WHERE user_id = 100 limit 10001 +---------------------------------------------------------------------- +``` diff --git a/content/en/docs/19.0/user-guides/sql/vtexplain.md b/content/en/docs/19.0/user-guides/sql/vtexplain.md new file mode 100644 index 000000000..5025608a2 --- /dev/null +++ b/content/en/docs/19.0/user-guides/sql/vtexplain.md @@ -0,0 +1,307 @@ +--- +title: Analyzing a SQL statement using VTEXPLAIN +weight: 1 +aliases: ['/docs/user-guides/vtexplain/'] +--- + +# Introduction + +This document covers the way Vitess executes a particular SQL statement using the [VTExplain tool](../../../reference/programs/vtexplain). +This tool works similarly to the MySQL `EXPLAIN` statement. +You can run `vtexplain` before you have a running Vitess cluster, which lets you quickly try different schema/vschema. +If you're already running a cluster, you can also use the [VEXPLAIN QUERIES|ALL|PLAN](../vexplain) command from a SQL console. + +## Prerequisites + +You can find a prebuilt binary version of the VTExplain tool in [the most recent release of Vitess](https://github.com/vitessio/vitess/releases/). + +You can also build the `vtexplain` binary in your environment. To build this binary, refer to the [build guide](/docs/contributing) for your OS. + +## Overview + +To successfully analyze your SQL queries and determine how Vitess executes each statement, follow these steps: + +1. Identify a SQL schema for the statement's source tables +1. Identify a VSchema for the statement's source tables +1. Run the VTExplain tool + +If you have a large number of queries you want to analyze for issues, based on a Vschema you’ve created for your database, you can read through a detailed scripted example [here](../vtexplain-in-bulk). + +## 1. Identify a SQL schema for tables in the statement + +In order to explain a statement, first identify the SQL schema for the tables that the statement uses. This includes tables that a query targets and tables that a DML statement modifies. + +### Example SQL Schema + +The following example SQL schema creates two tables, `users` and `users_name_idx`, each of which contain the columns `user_id` and `name`, and define both columns as a composite primary key. The example statements in step 3 include these tables. + +``` +CREATE TABLE users( + user_id bigint, + name varchar(128), + primary key(user_id) +); + +CREATE TABLE users_name_idx( + user_id bigint, + name varchar(128), + primary key(name, user_id) +); +``` + +## 2. Identify a VSchema for the statement's source tables + +Next, identify a [VSchema](../../../concepts/vschema) that contains the [Vindexes](../../../reference/features/vindexes) for the tables in the statement. + +### The VSchema must use a keyspace name. + +VTExplain requires a keyspace name for each keyspace in an input VSchema: + +``` +"keyspace_name": { + "_comment": "Keyspace definition goes here." +} +``` + +If no keyspace name is present, VTExplain will return the following error: + +``` +ERROR: initVtgateExecutor: json: cannot unmarshal bool into Go value of type map[string]json.RawMessage +``` + +### Example VSchema + +The following example VSchema defines a single keyspace `mainkeyspace` and three Vindexes, and specifies vindexes for each column in the two tables `users` and `users_name_idx`. The keyspace name `"mainkeyspace"` precedes the keyspace definition object. + +``` +{ + "mainkeyspace": { + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + }, + "md5": { + "type": "unicode_loose_md5", + "params": {}, + "owner": "" + }, + "users_name_idx": { + "type": "lookup_hash", + "params": { + "from": "name", + "table": "users_name_idx", + "to": "user_id" + }, + "owner": "users" + } + }, + "tables": { + "users": { + "column_vindexes": [ + { + "column": "user_id", + "name": "hash" + }, + { + "column": "name", + "name": "users_name_idx" + } + ], + "auto_increment": null + }, + "users_name_idx": { + "type": "", + "column_vindexes": [ + { + "column": "name", + "name": "md5" + } + ], + "auto_increment": null + } + } + } +} +``` + +## 3. Run the VTExplain tool + +To explain a query, pass the SQL schema and VSchema files as arguments to the `VTExplain` command. + +### Example: Explaining a SELECT query + +In the following example, the `VTExplain` command takes a `SELECT` query and returns the sequence of queries that Vitess runs in order to execute the query: + +``` +vtexplain --shards 8 --vschema-file vschema.json --schema-file schema.sql --replication-mode "ROW" --output-mode text --sql "SELECT * from users" +---------------------------------------------------------------------- +SELECT * from users + +1 mainkeyspace/-20: select * from users limit 10001 +1 mainkeyspace/20-40: select * from users limit 10001 +1 mainkeyspace/40-60: select * from users limit 10001 +1 mainkeyspace/60-80: select * from users limit 10001 +1 mainkeyspace/80-a0: select * from users limit 10001 +1 mainkeyspace/a0-c0: select * from users limit 10001 +1 mainkeyspace/c0-e0: select * from users limit 10001 +1 mainkeyspace/e0-: select * from users limit 10001 + +---------------------------------------------------------------------- + +``` + +In the example above, the output of `VTExplain` shows the sequence of queries that Vitess runs in order to execute the query. Each line shows the logical sequence of the query, the keyspace where the query executes, the shard where the query executes, and the query that executes, in the following format: + +``` +[Sequence number] [keyspace]/[shard]: [query] +``` + +In this example, each query has sequence number `1`, which shows that Vitess executes these in parallel. Vitess automatically adds the `LIMIT 10001` clause to protect against large results. + +### Example: Explaining an INSERT query + +In the following example, the `VTExplain` command takes an `INSERT` query and returns the sequence of queries that Vitess runs in order to execute the query: + +``` +vtexplain --shards 128 --vschema-file vschema.json --schema-file schema.sql --replication-mode "ROW" --output-mode text --sql "INSERT INTO users (user_id, name) VALUES(1, 'john')" +---------------------------------------------------------------------- +INSERT INTO users (user_id, name) VALUES(1, 'john') + +1 mainkeyspace/22-24: begin +1 mainkeyspace/22-24: insert into users_name_idx(`name`, user_id) values ('john', 1) +2 mainkeyspace/16-18: begin +2 mainkeyspace/16-18: insert into users(user_id, `name`) values (1, 'john') +3 mainkeyspace/22-24: commit +4 mainkeyspace/16-18: commit + +---------------------------------------------------------------------- + +``` + +The example above shows how Vitess handles an insert into a table with a secondary lookup Vindex: + +* At sequence number `1`, Vitess opens a transaction on shard `22-24` to insert the row into the `users_name_idx` table. +* At sequence number `2`, Vitess opens a second transaction on shard `16-18` to perform the actual insert into the `users` table. +* At sequence number `3`, the first transaction commits. +* At sequence number `4`, the second transaction commits. + +### Example: Explaining an uneven keyspace + +In previous examples, we used the `--shards` flag to set up an evenly-sharded keyspace, where each shard covers the same fraction of the keyrange. +`VTExplain` also supports receiving a JSON mapping of shard ranges to see how Vitess would handle a query against an arbitrarly-sharded keyspace. + +To do this, we first create a JSON file containing a mapping of keyspace names to shardrange maps. +The shardrange map has the same structure as the output of running `vtctl FindAllShardsInKeyspace `. + +``` +{ + "mainkeyspace": { + "-80": { + "primary_alias": { + "cell": "test", + "uid": 100 + }, + "primary_term_start_time": { + "seconds": 1599828375, + "nanoseconds": 664404881 + }, + "key_range": { + "end": "gA==" + }, + "is_primary_serving": true + }, + "80-90": { + "primary_alias": { + "cell": "test", + "uid": 200 + }, + "primary_term_start_time": { + "seconds": 1599828344, + "nanoseconds": 868327074 + }, + "key_range": { + "start": "gA==", + "end": "kA==" + }, + "is_primary_serving": true + }, + "90-a0": { + "primary_alias": { + "cell": "test", + "uid": 300 + }, + "primary_term_start_time": { + "seconds": 1599828405, + "nanoseconds": 152120945 + }, + "key_range": { + "start": "kA==", + "end": "oA==" + }, + "is_primary_serving": true + }, + "a0-e8": { + "primary_alias": { + "cell": "test", + "uid": 400 + }, + "primary_term_start_time": { + "seconds": 1599828183, + "nanoseconds": 911677983 + }, + "key_range": { + "start": "oA==", + "end": "6A==" + }, + "is_primary_serving": true + }, + "e8-": { + "primary_alias": { + "cell": "test", + "uid": 500 + }, + "primary_term_start_time": { + "seconds": 1599827865, + "nanoseconds": 770606551 + }, + "key_range": { + "start": "6A==" + }, + "is_primary_serving": true + } + } +} + +``` + +After having saved that to a file called `shardmaps.json`: + +``` +vtexplain --vschema-file vschema.json --schema-file schema.sql --ks-shard-map "$(cat shardmaps.json)" --replication-mode "ROW" --output-mode text --sql "SELECT * FROM users; SELECT * FROM users WHERE id IN (10, 17, 42, 1000);" +---------------------------------------------------------------------- +SELECT * FROM users + +1 mainkeyspace/-80: select * from users limit 10001 +1 mainkeyspace/80-90: select * from users limit 10001 +1 mainkeyspace/90-a0: select * from users limit 10001 +1 mainkeyspace/a0-e8: select * from users limit 10001 +1 mainkeyspace/e8-: select * from users limit 10001 + +---------------------------------------------------------------------- +SELECT * FROM users WHERE id IN (10, 17, 42, 1000) + +1 mainkeyspace/-80: select * from users where id in (10, 17, 42, 1000) limit 10001 +1 mainkeyspace/80-90: select * from users where id in (10, 17, 42, 1000) limit 10001 +1 mainkeyspace/90-a0: select * from users where id in (10, 17, 42, 1000) limit 10001 +1 mainkeyspace/a0-e8: select * from users where id in (10, 17, 42, 1000) limit 10001 +1 mainkeyspace/e8-: select * from users where id in (10, 17, 42, 1000) limit 10001 + +---------------------------------------------------------------------- + +``` + + +## See also + +* For detailed configuration options for VTExplain, see the [VTExplain syntax reference](../../../reference/programs/vtexplain). diff --git a/content/en/docs/19.0/user-guides/vschema-guide/_index.md b/content/en/docs/19.0/user-guides/vschema-guide/_index.md new file mode 100644 index 000000000..c60d42ebf --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/_index.md @@ -0,0 +1,5 @@ +--- +title: VSchema and Query Serving +description: Configuring VSchema for serving queries +weight: 1 +--- diff --git a/content/en/docs/19.0/user-guides/vschema-guide/advanced-vschema.md b/content/en/docs/19.0/user-guides/vschema-guide/advanced-vschema.md new file mode 100644 index 000000000..a7c01e848 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/advanced-vschema.md @@ -0,0 +1,205 @@ +--- +title: Advanced VSchema Properties +weight: 20 +--- + +With the exception of Multi-Column Vindexes, advanced VSchema Properties do not have DDL constructs. They can only be updated through `vtctld` CLI commands. + +## Multi-Column Vindexes + +Multi-Column Vindexes are useful in the following two use cases: + +* Grouping customers by their regions so they can be hosted in specific geographical locations. This may be required for compliance and also to achieve better performance. +* For a multi-tenant system, grouping all rows of a tenant in a separate set of shards. This limits the fan out of queries if searching only for rows that are related to a single tenant. + +In both cases the leading column is the region or tenant, and is used to form the first few bits of the `keyspace_id`. The second column is used for the bits that follow. Since Vitess shards by keyrange, this approach will naturally group all rows of a region or tenant within the same shard, or within a group of consecutive shards. Since each shard is its own MySQL cluster, these can then be deployed to different regions as needed. + +Please refer to [Region-based Sharding](../../configuration-advanced/region-sharding) for an example on how to use the `region_json` vindex and [Subsharding Vindex](../subsharding-vindex) for the more generic multicol vindex. + +#### Alternate approach + +You have the option to pre-combine the region and id bits into a single column and use that as an input for a single column vindex. This approach achieves the same goals as a multi-column vindex. + +The downside of this approach is that it is harder to migrate an id to a different region and you won't get the query serving support for routing queries to subset of shards if only the first few columns of a multicol vindex are provided. + +## Reference Tables + +Sharded databases often need the ability to join their tables with smaller “reference” tables. For example, the `product` table could be seen as a reference table. Other use cases are tables that map static information like zip code to city, etc. + +Joining against these tables across keyspaces results in cross-shard joins that may not be very efficient or fast. + +Vitess allows you to create a table in a sharded keyspace as a reference table. This means that it will treat the table as having an identical set of rows across all shards. A query that joins a sharded table against such reference tables is then performed locally within each shard. + +A reference table should not have any vindex, and is defined in the VSchema as a reference type: + +```json +{ + "sharded": true, + "tables": { + "zip_detail": { + "type": "reference" + } + } +} +``` +
    + +#### Source Tables + +Vitess will optimize reference tables routing when joined to a table within the same keyspace. Additional routing optimizations can be enabled by specifying the `source` of a reference table. When a reference table specifies a `source` table: + + * A `SELECT ... JOIN` (or equivalent `SELECT ... WHERE`) will try to route the + query to the keyspace of the table to which the reference (or source) table + is being joined. + * An `INSERT`, `UPDATE`, or `DELETE` uses the keyspace of the source table. + +For example: + +```json +{ + "sharded": true, + "tables": { + "zip_detail": { + "type": "reference", + "source": "unsharded_is.zip_detail" + } + } +} +``` +
    + +There are some constraints on `source`: + + * It must be a keyspace-qualified table name, e.g. `unsharded_ks.zip_detail`. + * It must refer to an existing table in an existing keyspace. + * It must refer to a table in a different keyspace. + * It must refer to a table in an unsharded keyspace. + * Any given value for `source` may appear at most once per-keyspace. + +#### Materialization + +It may become a challenge to keep a reference table correctly updated across all shards. Vitess supports the [Materialize](../../migration/materialize) feature that allows you to maintain the original table in an unsharded keyspace and automatically propagate changes to that table in real-time across all shards. + +## Column List + +The VSchema allows you to specify the list of columns along with their types for every table. This allows Vitess to make optimization decisions where necessary. + +For example, specifying that a column contains numeric data allows VTGate to not request further collation specific information (`weight_string`) if additional sorting is needed after collecting results from all shards. + +For example, issuing this query against `customer` would add the `weight_string` column while sending the query to the vttablets: + +```json +Query - select integer_col from customer order by integer_col; +Plan - +{ + "QueryType": "SELECT", + "Original": "select integer_col from customer order by integer_col", + "Instructions": { + "OperatorType": "Route", + "Variant": "SelectScatter", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select integer_col, weight_string(integer_col) from `customer` where 1 != 1", + "OrderBy": "0 ASC", + "Query": "select integer_col, weight_string(integer_col) from `customer` order by integer_col asc", + "Table": "`customer`" + } +} +``` + +However, we can modify the VSchema as follows: + +```json + "customer": { + "column_vindexes": [{ + "column": "customer_id", + "name": "hash" + }], + "auto_increment": { + "column": "customer_id", + "sequence": "product.customer_seq" + }, + "columns": [{ + "name": "integer_col", + "type": "INT16" + }] + } +``` + +Re-issuing the same query will now not use `weight_string`: + +```json +Query - select integer_col from customer order by integer_col; +Plan - +{ + "QueryType": "SELECT", + "Original": "select integer_col from customer order by integer_col", + "Instructions": { + "OperatorType": "Route", + "Variant": "SelectScatter", + "Keyspace": { + "Name": "customer", + "Sharded": true + }, + "FieldQuery": "select integer_col from `customer` where 1 != 1", + "OrderBy": "0 ASC", + "Query": "select integer_col from `customer` order by integer_col asc", + "Table": "`customer`" + } +} +``` + +Specifying columns against tables also allows VTGate to resolve ambiguous naming of columns against the right tables. + +#### Authoritative List + +If you have listed all columns of a table in the VSchema, you can add the `column_list_authoritative` flag to the table: + +```json + "customer": { + "column_vindexes": [{ + "column": "customer_id", + "name": "hash" + }], + "auto_increment": { + "column": "customer_id", + "sequence": "product.customer_seq" + }, + "columns": [{ + "name": "uname", + "type": "VARCHAR" + }], + "column_list_authoritative": true + } +``` + +This flag causes VTGate to automatically expand expressions like `select *` or insert statements that don’t specify the column list. + +The caveat about using this feature is that you have to keep this column list in sync with the underlying schema. + +#### Automatic Schema Tracking + +Vtgates now also have the capability to track the schema changes and populate the columns list on its own by contacting the vttablets. To know more about this feature, read [here](../../../reference/features/schema-tracking). +This feature tracks the underlying schema and sets the authoritative column list. + +## Routing Rules + +Routing Rules are an advanced method of redirecting queries meant for one table to another. They are just pointers and are analogous to symbolic links in a file system. You should generally not have to use routing rules in Vitess. + +Workflows like `MoveTables` make use of routing rules to create the existence of the target tables and manage traffic switch from source to target by manipulating these routing rules. + +For more information, please refer to the [Routing Rules](../../../reference/features/schema-routing-rules) section. + +## Foreign Key Mode + +Vitess supports multiple foreign key modes. A detailed analysis of these different modes can be found on the [foreign keys](../foreign-keys) page. + +Each keyspace can be configured to run with a different foreign key mode - +```json +{ + "sharded": true, + "foreignKeyMode": "FK_MANAGED" +} +``` 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 new file mode 100644 index 000000000..657494b60 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/backfill-vindexes.md @@ -0,0 +1,114 @@ +--- +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. +Only newer inserts cause automatic population of the lookup table. + +This backfill can be set up using the [CreateLookupVindex](#createlookupvindex) 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: + +* 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. +* Create the lookup vindex in the VSchema of the sharded keyspace: + * Give it a distinct name + * Specify the type from one of [predefined vindexes](../../../reference/features/vindexes/#predefined-vindexes) + * Under `params`: specify the properties of the lookup table + * Specify the `Owner` as the main table +* Associate the column of the owner table with the new Vindex. + +### CreateLookupVindex + +vtctld supports the [CreateLookupVindex](../../configuration-advanced/createlookupvindex) 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. +{{< /warning >}} + +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) + +To create such a lookup vindex on a real Vitess cluster, you can use the following instructions: + +#### Unique Lookup Vindex Example + +*Continued from [Unique Lookup Vindex Page](../unique-lookup)* + +Save the following json into a file, say `corder_keyspace_idx.json`: + +```json +{ + "sharded": true, + "vindexes": { + "corder_keyspace_idx": { + "type": "consistent_lookup_unique", + "params": { + "table": "product.corder_keyspace_idx", + "from": "corder_id", + "to": "keyspace_id" + }, + "owner": "corder" + } + }, + "tables": { + "corder": { + "column_vindexes": [{ + "column": "corder_id", + "name": "corder_keyspace_idx" + }], + } + } +} +``` + +And issue the vtctldclient command: + +```sh +$ vtctldclient --server CreateLookupVindex -- --tablet_types=REPLICA customer "$(cat corder_keyspace_idx.json)" +``` + +The workflow will automatically create the necessary Primary Vindex entries for vindex table `corder_keyspace_idx` knowing that it is sharded. + +#### Non-unique Lookup Vindex Example + +*Continued from [Non-unique Lookup Vindex Page](../non-unique-lookup)* + +Save the following json into a file, say `oname_keyspace_idx.json`: + +```json +{ + "sharded": true, + "vindexes": { + "oname_keyspace_idx": { + "type": "consistent_lookup", + "params": { + "table": "customer.oname_keyspace_idx", + "from": "oname,corder_id", + "to": "keyspace_id" + }, + "owner": "corder" + } + }, + "tables": { + "corder": { + "column_vindexes": [{ + "columns": ["oname", "corder_id"], + "name": "oname_keyspace_idx" + }] + } + } +} +``` + +And issue the vtctldclient command: + +```sh +$ vtctldclient --server CreateLookupVindex -- --tablet_types=REPLICA customer "$(cat oname_keyspace_idx.json)" +``` + +The workflow will automatically create the necessary Primary Vindex entries for vindex table `oname_keyspace_idx` knowing that it is sharded. diff --git a/content/en/docs/19.0/user-guides/vschema-guide/foreign-keys.md b/content/en/docs/19.0/user-guides/vschema-guide/foreign-keys.md new file mode 100644 index 000000000..abe29e941 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/foreign-keys.md @@ -0,0 +1,43 @@ +--- +title: Foreign Keys in Vitess +weight: 8 +--- + +For running foreign keys in Vitess, the users have a few options. Let's explore each of them in detail. + +### Vitess Unaware of Foreign Keys + +Users can run Vitess such that it doesn't know about or care for the foreign key constraints existing on MySQL. To run Vitess in this mode, `foreignKeyMode` VSchema property has to be set to `FK_UNMANAGED` for the given keyspace. This is the default mode for Vitess as well. + +It is up to the users to configure the foreign keys in MySQL such that rows that are related by foreign keys end up living in the same shard. +To this end, users can configure tables related by foreign keys to use the same shared vindex. More detail about this can be read in [shared vindexes](../shared-vindexes/#foreign-keys). + +#### Limitations + +- In a sharded keyspace, the current restrictions require the schema to be structured such that rows for tables linked by foreign keys need to live on the same shard. This constrains schema design and sharding key options. +- If `ON DELETE CASCADE`, `ON UPDATE CASCADE`, `ON DELETE SET NULL`, etc reference actions are used for foreign keys that cause a change on a child table when the parent is updated, MySQL doesn't report the updates on the child table in the binary log. They happen at the InnoDB level. This causes VReplication to not see the updates on the child, causing issues in [MoveTables](../../migration/move-tables/) and other VReplication based workflows. +- [OnlineDDL](../../schema-changes/managed-online-schema-changes/) doesn't work well with tables that have foreign key constraints on them. + +### Vitess Aware Foreign Keys [EXPERIMENTAL] + +{{< info >}} +Please note, that in this version of Vitess, this mode is experimental and should be used cautiously. +{{< /info >}} + +Users can run Vitess such that it keeps track of all the foreign key constraints using the schema tracker. To run Vitess in this mode, `foreignKeyMode` VSchema property has to be set to `FK_MANAGED` for the given keyspace. + +In this mode, Vitess takes care of splitting up DMLs that would cause updates on a child table in a foreign key constraint. All the queries on MySQL are executed such that InnoDB doesn't end up running any updates which don't make their way into the binary log. This allows VReplication to work properly, thus relaxing one of the limitations of the previous approach. + +For more details on what operations Vitess takes please refer to the [design document for foreign keys](https://github.com/vitessio/vitess/issues/12967). + +#### Limitations + +- Currently, Vitess only supports shard-scoped foreign key constraints even in the managed mode. Support for cross-shard foreign keys is underway. +- `UPDATE` statements only support updating to a literal value. For example, `UPDATE t1 SET col1 = 3 WHERE id = col + 1` is accepted, but `UPDATE t1 SET col1 = col + 3` is not. +- [OnlineDDL](../../schema-changes/managed-online-schema-changes/) doesn't work well with tables that have foreign key constraints on them. + +### Vitess Disallows Foreign Keys + +Users can run Vitess such that it explicitly disallows any DDL statements that try to create a foreign key constraint. To run Vitess in this mode, `foreignKeyMode` VSchema property has to be set to `FK_DISALLOW` for the given keyspace. + +This mode is for users that don't use foreign keys and want to prevent accidentally introducing them in their schema. diff --git a/content/en/docs/19.0/user-guides/vschema-guide/img/vschema1.png b/content/en/docs/19.0/user-guides/vschema-guide/img/vschema1.png new file mode 100644 index 000000000..f85138de2 Binary files /dev/null and b/content/en/docs/19.0/user-guides/vschema-guide/img/vschema1.png differ diff --git a/content/en/docs/19.0/user-guides/vschema-guide/img/vschema2.png b/content/en/docs/19.0/user-guides/vschema-guide/img/vschema2.png new file mode 100644 index 000000000..85ec159f2 Binary files /dev/null and b/content/en/docs/19.0/user-guides/vschema-guide/img/vschema2.png differ diff --git a/content/en/docs/19.0/user-guides/vschema-guide/lookup-as-primary.md b/content/en/docs/19.0/user-guides/vschema-guide/lookup-as-primary.md new file mode 100644 index 000000000..0d15ccf07 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/lookup-as-primary.md @@ -0,0 +1,146 @@ +--- +title: Lookup as Primary Vindex +weight: 10 +--- + +It is likely that a customer order goes through a life cycle of events. This would best be represented in a separate `corder_event` table that will contain a `corder_id` column as a foreign key into `corder.corder_id`. It would also be beneficial to co-locate the event rows with their associated order. + +Just like we shared the `hash` vindex between `customer` and `corder`, we can share `corder_keyspace_idx` between `corder` and `corder_event`. We can also make it the Primary Vindex for `corder_event`. When an order is created, the lookup row for it is also created. Subsequently, an insert into `corder_event` will request the vindex to compute the `keyspace_id` for that `corder_id`, and that will succeed because the lookup entry for it already exists. This is where the significance of the owner table comes into play: The owner table creates the entries, whereas other tables only read those entries. + +Inserting a `corder_event` row without creating a corresponding `corder` entry will result in an error. This behavior is in line with the traditional foreign key constraint enforced by relational databases. + +Sharing the lookup vindex also has the additional benefit of saving space because we avoid creating separate entries for the new table. + +We start with creating the sequence table in the `product` keyspace. + +Schema: + +```sql +create table corder_event_seq(id bigint, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into corder_event_seq(id, next_id, cache) values(0, 1, 3); +``` + +VSchema: + +```json + "corder_event_seq": { "type": "sequence" } +``` + +We then create the `corder_event` table in `customer`: + +```sql +create table corder_event(corder_event_id bigint, corder_id bigint, ename varchar(128), primary key(corder_id, corder_event_id)); +``` + +In the VSchema, there is no need to create a vindex because we are going to reuse the existing one: + +```json + "corder_event": { + "column_vindexes": [{ + "column": "corder_id", + "name": "corder_keyspace_idx" + }], + "auto_increment": { + "column": "corder_event_id", + "sequence": "product.corder_event_seq" + } + } +``` + +Alternate VSchema DDL: + +```sql +alter vschema add sequence product.corder_event_seq; +alter vschema on customer.corder_event add vindex corder_keyspace_idx(corder_id); +alter vschema on customer.corder_event add auto_increment corder_event_id using product.corder_event_seq; +``` + +We can now insert rows in `corder_event` against rows in `corder`: + +```text +mysql> insert into corder(customer_id, product_id, oname) values (1,1,'gift'),(1,2,'gift'),(2,1,'work'),(3,2,'personal'),(4,1,'personal'); +Query OK, 5 rows affected (0.04 sec) + +mysql> insert into corder_event(corder_id, ename) values(1, 'paid'), (5, 'delivered'); +Query OK, 2 rows affected (0.01 sec) + +mysql> insert into corder_event(corder_id, ename) values(6, 'expect failure'); +ERROR 1105 (HY000): vtgate: http://sougou-lap1:12345/: execInsertSharded: getInsertShardedRoute: could not map [INT64(6)] to a keyspace id +``` + +As expected, inserting a row for a non-existent order results in an error. + +### Reversible Vindexes + +In Vitess, it is insufficient for a table to only have a Lookup Vindex. This is because it is not practical to reshard such a table. The overhead of performing a lookup before redirecting every row event to a new shard would be prohibitively expensive. + +To overcome this limitation, we must add a column with a non-lookup vindex, also known as Functional Vindex to the table. By rule, the Primary Vindex computes the keyspace id of the row. This means that the value of the column should also be such that it yields the same keyspace id. + +A Reversible Vindex is one that can back-compute the column value from a given keyspace id. If such a vindex is used for this new column, then Vitess will automatically perform this work and fill in the correct value for it. The list of vindex properties, like Functional, Reversible, etc. are listed in the [Vindexes Reference](../../../reference/features/vindexes). + +In other words, adding a column with a vindex that is both Functional and Reversible allows Vitess to auto-fill the values, thereby avoiding any impact to the application logic. + +The `binary` vindex is one that yields the input value itself as the `keyspace_id`, and is naturally reversible. Using this Vindex will generate the `keyspace_id` as the column value. The modified schema for the table will be as follows: + +```sql +create table corder_event(corder_event_id bigint, corder_id bigint, ename varchar(128), keyspace_id varbinary(10), primary key(corder_id, corder_event_id)); +``` + +We create a vindex instantiation for `binary`: + +```json + "binary": { + "type": "binary" + } +``` + +Modify the table VSchema: + +```json + "corder_event": { + "column_vindexes": [{ + "column": "corder_id", + "name": "corder_keyspace_idx" + }, { + "column": "keyspace_id", + "name": "binary" + }], + "auto_increment": { + "column": "corder_event_id", + "sequence": "product.corder_event_seq" + } + } +``` + +Alternate VSchema DDL: + +```sql +alter vschema on customer.corder_event add vindex `binary`(keyspace_id) using `binary`; +``` + +Note that `binary` needs to be backticked because it is a keyword. + +After these modifications, we can now observe that the `keyspace_id` column is getting automatically populated: + +```text +mysql> insert into corder(customer_id, product_id, oname) values (1,1,'gift'),(1,2,'gift'),(2,1,'work'),(3,2,'personal'),(4,1,'personal'); +Query OK, 5 rows affected (0.01 sec) + +mysql> insert into corder_event(corder_id, ename) values(1, 'paid'), (5, 'delivered'); +Query OK, 2 rows affected (0.01 sec) + +mysql> select corder_event_id, corder_id, ename, hex(keyspace_id) from corder_event; ++-----------------+-----------+-----------+------------------+ +| corder_event_id | corder_id | ename | hex(keyspace_id) | ++-----------------+-----------+-----------+------------------+ +| 1 | 1 | paid | 166B40B44ABA4BD6 | +| 2 | 5 | delivered | D2FD8867D50D2DFE | ++-----------------+-----------+-----------+------------------+ +2 rows in set (0.00 sec) +``` + +There is no support for backfilling the reversible vindex column yet. This will be added soon. + +{{< info >}} +The original `keyspace_id` for all these rows came from `customer_id`. Since `hash` is also a reversible vindex, reversing the `keyspace_id` using `hash` will yield the `customer_id`. We could instead leverage this knowledge to replace `keyspace_id+binary` with `customer_id+hash`. Vitess will auto-populate the correct value. Using this approach may be more beneficial because `customer_id` is a value the application can understand and make use of. +{{< /info >}} diff --git a/content/en/docs/19.0/user-guides/vschema-guide/non-unique-lookup.md b/content/en/docs/19.0/user-guides/vschema-guide/non-unique-lookup.md new file mode 100644 index 000000000..5b224ac99 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/non-unique-lookup.md @@ -0,0 +1,157 @@ +--- +title: Non-Unique Lookup Vindexes +weight: 9 +--- + +The `oname` column in `corder` can contain duplicate values. There may be a need in the application to frequently search by this column: + +```sql +select * from corder where oname='gift' +``` + +To prevent this query from resulting in a full scatter, we will need to create a lookup vindex for it. But this time, it will need to be non-unique. However, the fact that duplicates are allowed leads to a complication with the lookup table approach. Let us look at the insert query: + +```sql +insert into corder(customer_id, product_id, oname) values (1,1,'gift'),(1,2,'gift'),(2,1,'work'),(3,2,'personal'),(4,1,'personal'); +``` + +We see that `customer_id 1` has two rows where the `oname` is `gift`. If we try to create entries for those two in a lookup table, they would be identical: + +```text ++-----------+--------------+ +| oname | hex(keyspace_id) | ++-----------+--------------+ +| gift | 166B40B44ABA4BD6 | (corder_id=1) +| gift | 166B40B44ABA4BD6 | (corder_id=2) ++-----------+--------------+ +``` + +To disambiguate this situation, non-unique lookup vindexes require you to add additional columns to the lookup table. They are typically the Primary Key of the main table. For the sake of demonstration, let us create this as a sharded table in the `customer` keyspace: + +```sql +create table oname_keyspace_idx(oname varchar(128), corder_id bigint, keyspace_id varbinary(10), primary key(oname, corder_id)); +``` + +Note that the primary key includes the `oname` column as well as the `corder_id` column. + +Because `oname` is a text column, the recommended Primary Vindex for it would be `unicode_loose_md5`, which also requires a vindex instantiation: + +“vindexes” section: + +```json + "unicode_loose_md5": { + "type": "unicode_loose_md5" + } +``` + +“tables” section: + +```json + "oname_keyspace_idx": { + "column_vindexes": [{ + "column": "oname", + "name": "unicode_loose_md5" + }] + } +``` + +The lookup vindex should reference these new columns as follows: + +```json + "oname_keyspace_idx": { + "type": "consistent_lookup", + "params": { + "table": "customer.oname_keyspace_idx", + "from": "oname,corder_id", + "to": "keyspace_id" + }, + "owner": "corder" + } +``` + +{{< info >}} +This Vindex could also be seen as a multi-column Unique Lookup Vindex: For a given pair of `oname,corder_id` as input, the result can only yield a single `keyspace_id`. However, the `consistent_lookup` vindex functionality only supports resolution using the first column `oname`. In the future, we may add the ability to use both columns as input if they are present in the `where` clause. This may result in the merger of `consistent_lookup` with a multi-column version of `consistent_lookup_unique` that can also perform non-unique lookups on a subset of the inputs. +{{< /info >}} + +Finally, we tie the associated columns in `corder` to the vindex: + +```json + "corder": { + "column_vindexes": [{ + "column": "customer_id", + "name": "hash" + }, { + "column": "corder_id", + "name": "corder_keyspace_idx" + }, { + "columns": ["oname", "corder_id"], + "name": "oname_keyspace_idx" + }], + "auto_increment": { + "column": "corder_id", + "sequence": "product.corder_seq" + } + } +``` + +Alternate VSchema DDL: + +```sql +alter vschema on customer.oname_keyspace_idx add vindex unicode_loose_md5(oname) using unicode_loose_md5; +alter vschema on customer.corder add vindex oname_keyspace_idx(oname,corder_id) using consistent_lookup with owner=`corder`, table=`customer.oname_keyspace_idx`, from=`oname,corder_id`, to=`keyspace_id`; +``` + +We can now look at the effects of this change: + +```text +mysql> insert into corder(customer_id, product_id, oname) values (1,1,'gift'),(1,2,'gift'),(2,1,'work'),(3,2,'personal'),(4,1,'personal'); +Query OK, 5 rows affected (0.03 sec) + +mysql> use `customer:-80`; +Database changed +mysql> select oname, corder_id, hex(keyspace_id) from oname_keyspace_idx; ++-------+-----------+------------------+ +| oname | corder_id | hex(keyspace_id) | ++-------+-----------+------------------+ +| gift | 1 | 166B40B44ABA4BD6 | +| gift | 2 | 166B40B44ABA4BD6 | +| work | 3 | 06E7EA22CE92708F | ++-------+-----------+------------------+ +3 rows in set (0.00 sec) + +mysql> use `customer:80-`; +Database changed +mysql> select oname, corder_id, hex(keyspace_id) from oname_keyspace_idx; ++----------+-----------+------------------+ +| oname | corder_id | hex(keyspace_id) | ++----------+-----------+------------------+ +| personal | 4 | 4EB190C9A2FA169C | +| personal | 5 | D2FD8867D50D2DFE | ++----------+-----------+------------------+ +2 rows in set (0.00 sec) +``` + +We can see that the lookup table is following its own sharding scheme and distributing its rows according to the value of the `oname` column. + +Deleting one of the `corder` rows results in the corresponding lookup row being deleted: + +```text +mysql> delete from corder where corder_id=1; +Query OK, 1 row affected (0.00 sec) + +mysql> select oname, corder_id, hex(keyspace_id) from oname_keyspace_idx where oname='gift'; ++-------+-----------+------------------+ +| oname | corder_id | hex(keyspace_id) | ++-------+-----------+------------------+ +| gift | 2 | 166B40B44ABA4BD6 | ++-------+-----------+------------------+ +1 row in set (0.00 sec) +``` + +{{< info >}} +You would typically have to create a MySQL non-unique index on `oname` for queries to work efficiently. While these vindexes and indexes improve read performance, the trade-off is that they also increase storage requirements and amplify writes when inserting rows. +{{< /info >}} + +### Backfill + +To Backfill the vindex on an existing table refer to [Backfill Vindexes](../backfill-vindexes) diff --git a/content/en/docs/19.0/user-guides/vschema-guide/overview.md b/content/en/docs/19.0/user-guides/vschema-guide/overview.md new file mode 100644 index 000000000..dc58d5520 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/overview.md @@ -0,0 +1,34 @@ +--- +title: Overview +weight: 2 +--- + +One of the goals for Vitess is to provide a unified view for a large number of MySQL clusters distributed across multiple data centers and regions. + +Vitess achieves this goal by allowing the application to connect to any VTGate server, and that server gives you the semblance of being connected to a single MySQL server. The metadata that maps the logical view to the physical MySQL servers is stored in the topology. + +In this logical view, a Vitess keyspace is the equivalent of a MySQL database. In many cases, this is a one-to-one mapping where a keyspace directly corresponds to a physical MySQL server with a single database. However, a Vitess keyspace can also be sharded. If so, a single keyspace would map to multiple MySQL servers behind the scenes. + +The topology is typically spread across multiple Topo Servers: The Global Topo server contains global information, like the list of keyspaces, shards and cells. This information gets deployed into cell-specific topo servers. Each cell-specific Topo Server contains additional information about vttablets and MySQL servers running in that cell. With this architecture, an outage in one cell does not affect other cells. + +The topo also stores a VSchema for each keyspace. For an unsharded keyspace, the vschema is a simple list of table names. If a keyspace is sharded, then it must contain additional metadata about the sharding scheme for each table, and how they relate to each other. When a query is received by VTGate, the information in the vschema is used to make decisions about how to serve the query. In some cases, it will result in the query being routed to a single shard. In other cases, it could result in the query being sent to all shards, etc. + +This guide explains how to build vschemas for Vitess keyspaces. + +### Demo + +To illustrate the various features of the VSchema, we will make use of the [demo app](https://github.com/vitessio/vitess/tree/main/examples/demo). After installing Vitess, you can launch this demo by running `go run demo.go`. Following this, you can visit http://localhost:8000 to view the tables, issue arbitrary queries, and view their effects. + +Alternatively, you can also connect to Vitess using a MySQL client: `mysql -h 127.0.0.1 -P 12348`. + +The demo models a set of tables that are similar to those presented in the [Getting Started](../../../get-started/local) guide, but with more focus on the VSchema. + +Note that the demo brings up a test process called vtcombo (instead of a real Vitess cluster), which is functionally equivalent to all the components of Vitess, but within a single process. + +You can also use the demo app to follow the steps of this user guide. If so, you can start by emptying out the files under `schema/product` and `schema/customer`, and incrementally making the changes presented in the steps that follow. + +### VSchema DDL + +The demo describes the VSchema JSON syntax. Many of the changes can be executed by issuing special DDL commands that Vitess understands. Wherever applicable, we have provided the equivalent DDL construct you could apply if you were running a live system. All the DDLs are also listed in the [vschema_ddls.sql](https://github.com/vitessio/vitess/blob/main/examples/demo/vschema_ddls.sql) file. + +It is generally recommended that you get familiar with the JSON syntax as it will be useful for troubleshooting if something does not work as intended. diff --git a/content/en/docs/19.0/user-guides/vschema-guide/pictorial.md b/content/en/docs/19.0/user-guides/vschema-guide/pictorial.md new file mode 100644 index 000000000..0974a289b --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/pictorial.md @@ -0,0 +1,14 @@ +--- +title: Pictorial Summary +weight: 25 +--- + +The following two diagrams highlight some of the relationships that exist between VSchema elements and the MySQL tables. + +### product and customer + +![vschema1](../img/vschema1.png) + +### corder + +![vschema2](../img/vschema2.png) diff --git a/content/en/docs/19.0/user-guides/vschema-guide/sequences.md b/content/en/docs/19.0/user-guides/vschema-guide/sequences.md new file mode 100644 index 000000000..8fa2282ed --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/sequences.md @@ -0,0 +1,96 @@ +--- +title: Sequences +weight: 6 +--- + +The sharded `customer` table we created did not have an auto-increment column. The Vitess Sequence feature can be used to emulate the same behavior as MySQL’s auto-increment. A Vitess sequence is a single row unsharded tablet that keeps track of ids issued so far. Additionally, a configurable number of values can be cached by vttablet to minimize round trips into MySQL. + +We will create the sequence table in the unsharded `product` keyspace as follows: + +```sql +create table customer_seq(id bigint, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into customer_seq(id, next_id, cache) values(0, 1, 3); +``` + +Note the special comment `vitess_sequence`. This instructs vttablet that this is a special table. + +The table needs to be pre-populated with a single row where: + +* `id` must always be 0 +* `next_id` should be set to the next (starting) value of the sequence +* `cache` is the number of values to cache before updating the table for the next value. This value should be set to a fairly large number like 1000. We have set the value to `3` mainly to demonstrate how the feature works. + +Since this is a special table, we have to inform the vschema by giving it a `sequence` type. + +``` + "customer_seq": { "type": "sequence" } +``` + +Once setup this way, you can use the special `select next` syntax to generate values from this sequence: + + +```text +mysql> select next 2 values from customer_seq; ++---------+ +| nextval | ++---------+ +| 1 | ++---------+ +1 row in set (0.00 sec) + +mysql> select next 1 values from customer_seq; ++---------+ +| nextval | ++---------+ +| 3 | ++---------+ +1 row in set (0.00 sec) +``` + +The construct returns the first of the N values generated. + +However, this is insufficient to emulate MySQL’s auto-increment behavior. To achieve this, we have to inform the VSchema that the `customer_id` column should use this sequence to generate values if no value is specified. This is done by adding the following section to the `customer` table: + +```json + "auto_increment": { + "column": "customer_id", + "sequence": "product.customer_seq" + } +``` + +Alternate VSchema DDL: + +```sql +alter vschema add sequence product.customer_seq; +alter vschema on customer.customer add auto_increment customer_id using product.customer_seq; +``` + +With this, you can insert into `customer` without specifying the `customer_id`: + +```text +mysql> insert into customer(uname) values('alice'),('bob'),('charlie'),('dan'),('eve'); +Query OK, 5 rows affected (0.03 sec) + +mysql> use `customer:-80`; +Database changed +mysql> select * from customer; ++-------------+---------+ +| customer_id | uname | ++-------------+---------+ +| 1 | alice | +| 2 | bob | +| 3 | charlie | +| 5 | eve | ++-------------+---------+ +4 rows in set (0.00 sec) + +mysql> use `customer:80-`; +Database changed +mysql> select * from customer; ++-------------+-------+ +| customer_id | uname | ++-------------+-------+ +| 4 | dan | ++-------------+-------+ +1 row in set (0.00 sec) +``` diff --git a/content/en/docs/19.0/user-guides/vschema-guide/sharded.md b/content/en/docs/19.0/user-guides/vschema-guide/sharded.md new file mode 100644 index 000000000..a167931f8 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/sharded.md @@ -0,0 +1,132 @@ +--- +title: Sharded Keyspace +weight: 5 +--- + +A sharded keyspace allows you to split a large database into smaller parts by distributing the rows of each table into different shards. In Vitess, each shard is assigned a `keyrange`. Every row has a keyspace id, and this value decides the shard in which the row lives. For key-value stores, the keyspace id is dictated by the value of the key, also known as the sharding key. In Vitess, this is known as the Primary Vindex. But it differs from a sharding key in the following ways: + +* Any column or a set of columns can be chosen to be the primary vindex. +* The Vindex also decides the sharding function that controls how the data is distributed. +* The sharding function is pluggable, allowing for user-defined sharding schemes. + +Vitess provides many predefined vindex types. The most popular ones are: + +* `hash`: for numbers +* `unicode_loose_md5`: for text columns +* `binary_md5`: for binary columns + +In our example, we are going to designate `customer` as a sharded keyspace, and create a `customer` table in it. The schema for the table is as follows: + +```sql +create table customer(customer_id bigint, uname varchar(128), primary key(customer_id)); +``` + +In the VSchema, we need to designate which column should be the Primary Vindex, and choose the vindex type for it. The `customer_id` column seems to be the natural choice. Since it is a number, we will choose `hash` as the vindex type: + +```json +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "customer": { + "column_vindexes": [{ + "column": "customer_id", + "name": "hash" + }] + } + } +} +``` + +In the above section, we are instantiating a vindex named `hash` from the vindex type `hash`. Such instantiations are listed in the `vindexes` section of the vschema. The tables are expected to refer to the instantiated name. There are a few reasons why this additional level of indirection is necessary: + +* As we will see later, vindexes can be instantiated with different input parameters. In such cases, they have to have their own distinct names. +* Vindexes can be shared by tables, and this has special meaning. We will cover this in a later section. +* Vindexes can also be referenced as if they were tables and can be used to compute the keyspace id for a given input. + +The `column_vindexes` section is a list. This is because a table can have multiple vindexes. If so, the first vindex in the list must be the Primary Vindex. More information about vindexes can be found in the [Vindex Reference](../../../reference/features/vindexes). + +Alternate VSchema DDL: + +```sql +alter vschema on customer.customer add vindex hash(customer_id) using hash; +``` + +The DDL creates the `hash` vindex under the `vindexes` section, the `customer` table under the `tables` section, and associates the `customer_id` column to `hash`. For sharded keyspaces, the only way to create a table is using the above construct. This is because a primary vindex is mandatory for sharded tables. + +{{< info >}} +Every sharded table must have a Primary Vindex. A Primary Vindex must be instantiated from a vindex type that is Unique. `hash`, `unicode_loose_md5` and `binary_md5` are unique vindex types. +{{< /info >}} + +The demo brings up the `customer` table as two shards: `-80` and `80-`. For a `hash` vindex, input values of 1, 2 and 3 fall in the `-80` range, and 4 falls in the `80-` range. Restarting the demo with the updated configs should allow you to perform the following: + +```text +mysql> insert into customer(customer_id,uname) values(1,'alice'),(4,'dan'); +Query OK, 2 rows affected (0.00 sec) + +mysql> use `customer:-80`; +Database changed +mysql> select * from customer; ++-------------+-------+ +| customer_id | uname | ++-------------+-------+ +| 1 | alice | ++-------------+-------+ +1 row in set (0.00 sec) + +mysql> use `customer:80-`; +Database changed +mysql> select * from customer; ++-------------+-------+ +| customer_id | uname | ++-------------+-------+ +| 4 | dan | ++-------------+-------+ +1 row in set (0.00 sec) +``` + +You will notice that we used a special shard targeting construct: `use customer:-80`. Vitess allows you to use this hidden database name to bypass its routing logic and directly send queries to a specific shard. Using this construct, we are able to verify that the rows went to different shards. + +At the time of insert, the Primary Vindex is used to compute and assign a keyspace id to each row. This keyspace id gets used to decide where the row will be stored. Although a keyspace id is not explicitly stored anywhere, it must be seen as an unchanging property of that row; as if there was an invisible column for it. + +Consequently, you cannot make changes to a row that can cause the keyspace id to change. Such a change will be supported in the future through a shard move operation. Trying to change the value of a Primary Vindex results in an error: + +```text +mysql> update customer set customer_id=2 where customer_id=1; +ERROR 1235 (HY000): vtgate: http://sougou-lap1:12345/: unsupported: You can't update primary vindex columns. Invalid update on vindex: hash +``` + +A Primary Vindex can also be used to find rows if referenced in a where clause: + +```text +mysql> select * from customer where customer_id=1; ++-------------+-------+ +| customer_id | uname | ++-------------+-------+ +| 1 | alice | ++-------------+-------+ +1 row in set (0.00 sec) +``` + +If you run the above query in the demo app, the panel on the bottom right will show that the query was executed only on one shard. + +On the other hand, the query below will get sent to all shards because there is no where clause: + +```text +mysql> select * from customer; ++-------------+-------+ +| customer_id | uname | ++-------------+-------+ +| 4 | dan | +| 1 | alice | ++-------------+-------+ +2 rows in set (0.01 sec) +``` + +{{< info >}} +There is no implicit or predictable ordering for rows that are gathered from multiple shards. If a specific order is required, the query must include an `order by` clause. +{{< /info >}} diff --git a/content/en/docs/19.0/user-guides/vschema-guide/sharding-guidelines.md b/content/en/docs/19.0/user-guides/vschema-guide/sharding-guidelines.md new file mode 100644 index 000000000..5b4e0922e --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/sharding-guidelines.md @@ -0,0 +1,79 @@ +--- +title: Sharding Guidelines +weight: 3 +--- + +The following guidelines are not set in stone. They mainly establish a framework for making decisions. + +### Why + +There was a time when sharding used to be a line that one should avoid crossing for as long as possible. However, with Vitess considerably reducing the pain of sharding, we can look at leveraging some of its benefits much sooner than when a machine runs out of capacity: + +* Smaller blast radius: If a shard goes down, the outage affects a smaller percentage of the users. +* Improved resource utilization: It is difficult to pack large instances of servers efficiently across machines. It is much easier to utilize the capacity of the existing hardware if the shard sizes are relatively small. Orchestration systems like Kubernetes further facilitate such utilization. +* Reduced contention: MySQL itself runs a lot better when instance sizes are small. There is less internal contention, replicas tend to keep up more easily with their primary, etc. +* Improved maintenance: Operations like schema deployment can happen in parallel across all shards and finish much sooner than usual. + +There is a general worry that the complexity of deployment increases with the number of servers. However, this becomes a static cost once the necessary automation and monitoring is put in place. + +### Why not + +There are also reasons why you may want to avoid sharding. The main reason is that you may introduce inefficiencies by splitting data that would have been better off if it stayed together. Or, if your database is extremely small. + +However, if you reach a point where the data is starting to grow, sharding may become inevitable. + +### Moving Tables + +Typically, the first step you may perform is to split your database by moving some tables on to other databases. In Vitess parlance, we call this as splitting off keyspaces. The [MoveTables](../../migration/move-tables) workflow allows you to perform this with minimal impact to the application. + +### Resharding + +Beyond a certain point, it may not make sense to separate tables that are strongly related to each other. This is when resharding comes into play. Choosing the “sharding key” is often intuitively obvious. + +If you analyze the query pattern in the application, the query with the highest QPS will dictate the sharding key (or Primary Vindex). In our example below, we will be choosing `customer_id` as the Primary Vindex for the `customer` table. + +If there are queries with other where clauses on the same table, those would be candidates for secondary lookup vindexes. + +### Joins + +The next criteria to take into account are joins. If you are performing joins across tables, it will be beneficial to keep those rows together. In our example, we will be keeping the rows of the order table along with their customer. This grouping will allow us to efficiently perform operations like reading all orders placed by a customer. + +### Transactions + +It is important to keep transactions within a single shard whenever possible. + +Grouping related rows together usually results in transactions also falling within the same shard, but there are situations where this may not be possible. For such use-cases, Vitess supports [configurable atomicity levels for transactions that go across shards](../../configuration-advanced/shard-isolation-atomicity). + +In the cases where a cross-shard transaction simply cannot be avoided, the [usage of 2PC](../../../reference/features/two-phase-commit/) allows for atomic writes across shards in a single logical transaction. + +### Large Tenants + +If your application is tenant-based, it is possible that a single tenant may grow so big that they may not fit in one shard. If so, it is likely that the application is using a different key that has a higher cardinality than the tenant id. + +The question to ask oneself is: if the tenant were a single application by themselves, what would be their sharding key, and then shard by that key instead of the tenant id. + +Vitess now has support for [multi-column Vindexes](../advanced-vschema/#multi-column-vindexes). You can now shard by the tenant id and a secondary key. The two-column sharding approach allows you to group all data for a given tenant into a smaller set of shards rather than a random distribution. This may be beneficial for security or compliance reasons, in case the tenant would want their data to be physically isolated from other tenants. + +### Region Sharding + +The Vitess multi-column Vindex feature also allows you to locate data associated with regions in different geographical locations. For more details, see [Region-based Sharding](../../configuration-advanced/region-sharding). + +### Many-to-Many relationships + +Sharding works well only if the relationship between data is hierarchical (one-to-one or one-to-many). If a table has foreign keys into multiple other tables, you have to choose one based on the strongest relationship and group the rows by that foreign key. The rest of the relationships will incur cross-shard overheads. + +If more than one relationship is critically strong, you can look at the [Materialization](../../../reference/vreplication/materialize) feature which allows you to create a materialized view of the table that is sharded using the other relationship. The application will write to the source, and the other view will be automatically updated. + +### Course Correction + +It may happen that the original sharding decision is not working out. It may also be possible that the application evolves in such a way that the sharding decision you previously made does not make sense any more. + +In such cases, the [MoveTables](../../migration/move-tables) feature can be used to change the sharding key of existing tables. + +Essentially, Vitess removes the fear of making the wrong sharding decision because you can always change your mind later. + +### Rule of Thumb + +Although a Vitess shard can grow to many terabytes, we have seen that 250GB is the sweet spot. If your data size approaches this limit, it is time to think about splitting your data. + +Please also note that smaller shard sizes will backup more quickly. However, you will likely end up with more shards to backup, which may take more time to run in total, but can be run in parallel. diff --git a/content/en/docs/19.0/user-guides/vschema-guide/shared-vindexes.md b/content/en/docs/19.0/user-guides/vschema-guide/shared-vindexes.md new file mode 100644 index 000000000..6ecd20702 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/shared-vindexes.md @@ -0,0 +1,175 @@ +--- +title: Shared Vindexes and Foreign Keys +weight: 7 +--- + +Let us now look at creating the `corder` table that will contain orders placed by the customers. It will be beneficial to group the rows of the orders in the same shard as that of the customer that placed the orders. Doing things this way will allow for simpler join queries between `customer` and `corder`. There will also be transactional benefits: any transaction that also updates the customer row along with an order will be a single shard transaction. + +To make this happen in Vitess, all you have to do is specify that `corder.customer_id` uses the `hash` vindex, which is the same one used by `customer.customer_id`. + +This is one situation where a Primary Vindex conceptually differs from a traditional database Primary Key. Whereas a Primary Key makes a row unique, a Vitess Primary Vindex only yields a Unique value. But multiple rows with the same Primary Vindex value can exist. + +In other words, the Primary Vindex column need not be the primary key, or unique within MySQL. This is convenient for the `corder` table because we want customers to place multiple orders. In this case, all orders placed by a customer will have the same `customer_id`. The Primary Vindex for those will yield the same keyspace id as that of the customer. Therefore, all the rows for that customer’s orders will end up in the same shard along with the customer row. + +Since `corder` rows will need to have their own unique identifier, we also need to create a separate sequence for it in the product keyspace. + +```sql +create table corder_seq(id bigint, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into corder_seq(id, next_id, cache) values(0, 1, 3); +``` + +VSchema: + +```json + "corder_seq": { "type": "sequence" } +``` + +We create the `corder` table as follows: + +```sql +create table corder(corder_id bigint, customer_id bigint, product_id bigint, oname varchar(128), primary key(corder_id)); +``` + +VSchema: +```json + "corder": { + "column_vindexes": [{ + "column": "customer_id", + "name": "hash" + }], + "auto_increment": { + "column": "corder_id", + "sequence": "product.corder_seq" + } + } +``` + +Alternate VSchema DDL: + +```sql +alter vschema on customer.corder add vindex hash(customer_id); +alter vschema add sequence product.corder_seq; +alter vschema on customer.corder add auto_increment corder_id using product.corder_seq; +``` + +Inserting into `corder` yields the following results: + +```text +mysql> insert into corder(customer_id, product_id, oname) values (1,1,'gift'),(1,2,'gift'),(2,1,'work'),(3,2,'personal'),(4,1,'personal'); +Query OK, 5 rows affected (0.03 sec) + +mysql> use `customer:-80`; +Database changed +mysql> select * from corder; ++-----------+-------------+------------+----------+ +| corder_id | customer_id | product_id | oname | ++-----------+-------------+------------+----------+ +| 1 | 1 | 1 | gift | +| 2 | 1 | 2 | gift | +| 3 | 2 | 1 | work | +| 4 | 3 | 2 | personal | ++-----------+-------------+------------+----------+ +4 rows in set (0.00 sec) + +mysql> use `customer:80-`; +Database changed +mysql> select * from corder; ++-----------+-------------+------------+----------+ +| corder_id | customer_id | product_id | oname | ++-----------+-------------+------------+----------+ +| 5 | 4 | 1 | personal | ++-----------+-------------+------------+----------+ +1 row in set (0.00 sec) +``` + +As expected, orders are created in the same shard as their customer. Selecting orders by their customer id goes to a single shard: + +```text +mysql> select * from corder where customer_id=1; ++-----------+-------------+------------+-------+ +| corder_id | customer_id | product_id | oname | ++-----------+-------------+------------+-------+ +| 1 | 1 | 1 | gift | +| 2 | 1 | 2 | gift | ++-----------+-------------+------------+-------+ +2 rows in set (0.00 sec) +``` + +Joining `corder` with `customer` also goes to a single shard. This is also referred to as a local join: + +```text +mysql> select c.uname, o.oname, o.product_id from customer c join corder o on c.customer_id = o.customer_id where c.customer_id=1; ++-------+-------+------------+ +| uname | oname | product_id | ++-------+-------+------------+ +| alice | gift | 1 | +| alice | gift | 2 | ++-------+-------+------------+ +2 rows in set (0.01 sec) +``` + +Performing the join without a `customer_id` constraint still results in a local join, but the query is scattered across all shards: + +```text +mysql> select c.uname, o.oname, o.product_id from customer c join corder o on c.customer_id = o.customer_id; ++---------+----------+------------+ +| uname | oname | product_id | ++---------+----------+------------+ +| alice | gift | 1 | +| alice | gift | 2 | +| bob | work | 1 | +| charlie | personal | 2 | +| dan | personal | 1 | ++---------+----------+------------+ +5 rows in set (0.00 sec) +``` + +However, adding a join with `product` results in a cross-shard join for the product part ot the query: + +```text +mysql> select c.uname, o.oname, p.pname from customer c join corder o on c.customer_id = o.customer_id join product p on o.product_id = p.product_id; ++---------+----------+----------+ +| uname | oname | pname | ++---------+----------+----------+ +| alice | gift | monitor | +| alice | gift | keyboard | +| bob | work | monitor | +| charlie | personal | keyboard | +| dan | personal | monitor | ++---------+----------+----------+ +5 rows in set (0.01 sec) +``` + +Although the underlying work performed by Vitess is not visible here, you can see it in the bottom right panel if using the demo app. Alternatively, you can also stream this information with the following command: + +```text +curl localhost:12345/debug/querylog +[verbose output not shown] +``` + +### Foreign Keys + +More generically stated: If a table has a foreign key into another table, then Vitess can ensure that the related rows live in the same shard by making them share a common Unique Vindex. + +In cases where you choose to group rows based on their foreign key relationships, you have the option to enforce those constraints within each shard at the MySQL level. You can also configure cascade deletes as needed. However, overuse of foreign key constraints is generally discouraged in MySQL. + +Foreign key constraints across shards or keyspaces are not supported in Vitess. For example, you cannot specify a foreign key between `corder.product_id` and `product.product_id`. + +A more detailed analysis of foreign keys in Vitess can be found on the [foreign keys](../foreign-keys) page. + +### Many-to-Many relationships + +In the case where a table has relationships with multiple other tables, you can only choose one of those relationships for shard grouping. All other relationships will end up being cross-shard, and will incur cross-shard penalties. + +If a table has strong relationships with multiple other tables, and if performance becomes a challenge choosing either way, you can explore the [VReplication Materialization](../../../reference/vreplication/materialize) feature that allows you to materialize a table both ways. + +### Enforcing Uniqueness + +To enforce global uniqueness for a row in a sharded table, you have to have: + +* A Unique Vindex on the column +* A Unique constraint at the MySQL level + +A Primary Vindex coupled with a Primary Key constraint makes a row globally unique. + +A Unique Vindex can also be specified for a non-unique column. In such cases, it is likely that you will be using that column in a where clause, and will require a secondary non-unique index on it at the MySQL level. diff --git a/content/en/docs/19.0/user-guides/vschema-guide/subsharding-vindex.md b/content/en/docs/19.0/user-guides/vschema-guide/subsharding-vindex.md new file mode 100644 index 000000000..fcf4f12bc --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/subsharding-vindex.md @@ -0,0 +1,266 @@ +--- +title: Subsharding Vindex +weight: 15 +--- + +### Introduction + +A subsharding vindex is a functional unique vindex. It is constructed by using +a set of columns from the table to be sharded. If all the columns in this +vindex are provided in a query's `WHERE` clause, then the query is guaranteed to +be routed to a single shard. If an ordered subset of columns are provided, +starting with the first column in the vindex, then the query can usually be +routed to a subset of shards instead of all shards. + +### Use cases + +A common use case for a subsharding vindex is when a given entity’s data fits +on more than one shard (e.g a large tenant in a SaaS scenario) and there is +no suitable intermediary grouping construct. Storing that entity’s data across +all shards will lead to scatter queries. Scatter queries are especially expensive for +keyspaces with large numbers of shards. + +An additional use case could be geo-sharding, where the data for a particular +region should reside within a subset of shards which are co-located in that +region. + +### Prerequisite +The subsharding vindex only works with Gen4 query planner. + +### Usage + +This vindex is registered as `multicol` vindex. +It takes 3 parameters as input: + +1. `column_count` - the number of columns provided for using the vindex. +2. `column_vindex` - a list of functional vindexes, mapping to hashing functions, to be used on each column in turn to compute the hash value for that column. +3. `column_bytes` - number of bytes to be used from each column's hash value after applying its hashing function on it to produce keyspace id. These must sum to 8 bytes to make up the 64 bit keyspace ID. + +Example usage in VSchema: + +```json +"vindexes": { + "multicol_vdx": { + "type": "multicol", + "params": { + "column_count": "3", + "column_bytes": "1,3,4", + "column_vindex": "hash,binary,unicode_loose_xxhash" + } + } +} +``` +```json +"tables": { + "multicol_tbl": { + "column_vindexes": [ + { + "columns": ["cola","colb","colc"], + "name": "multicol_vdx" + } + ] + } +} +``` +`column_count` is a required parameter. +A maximum of 8 columns can be used in this vindex i.e. `column_count <= 8` + +`column_vindex` should contain the vindex names in a comma-separated list. It should be less than or equal to column_count. +The default vindex is `hash`, If a vindex is not provided for a column, then `hash` will be used for that column. +Each vindex in `column_vindex` should implement the following interface otherwise the initialization will fail. See below for the list of [standard Vitess vindexes](#hashing-function-implementation) that implement this interface. + +```go +// Hashing defines the interface for vindexes that export the Hash function to be used by multi-column vindex. +type Hashing interface { + Hash(id sqltypes.Value) ([]byte, error) +} +``` + +Here is an example of how the keyspace ID is constructed: + +``` +Given that we allocate bytes from the following columns: +c1 - 1 byte +c2 - 3 bytes +c3 - 4 bytes + +For the column Cn -> Cn.Hash(Cn_values)[0 : n_bytes_allocated_for_column] + +keyspace_id: +|_c1|_c2__c2__c2|_c3__c3__c3__c3| +|_0_|_1_|_2_|_3_|_4_|_5_|_6_|_7_| +``` + +`column_bytes` should contain the number of bytes for each column in a comma-separated list. The numbers should add up to 8. +If the number of bytes is not provided for all columns, they are inferred by assigning equal numbers to the remaining unassigned columns. + +Example 1: + +``` +Given: +column_count = 5 +column_bytes = 1, , 3 + +col 1 -> 1 +col 2 -> not provided +col 3 -> 3 +col 4 -> not provided +col 5 -> not provided + +Calculated: +remaining bytes = 8 - 1 - 3 -> 4 +remaining columns = 5 - 2 -> 3 +col 2 -> 2 +col 4 -> 1 +col 5 -> 1 +``` + +Example 2: +``` +given: 3 columns, 8 bytes +output: c1 -> 3, c2 -> 3, c3 -> 2 +``` + +Example 3: +``` +given: 3 columns, first column is 1 byte. +output: c1 -> 1, c2 -> 4, c3 -> 3 +``` + +### Hashing Function Implementation + +The Vindexes that can be used in a subsharding vindex by implementing the required hashing interface are: + +* `binary` +* `binary_md5` +* `hash` +* `numeric` +* `numeric_static_map` +* `reverse_bits` +* `unicode_loose_md5` +* `unicode_loose_xxhash` +* `xxhash` + + +### Example + +For a concrete example, assume we have a table with `BIGINT` columns: + +``` +CREATE TABLE t1 ( + c1 BIGINT NOT NULL, + c2 BIGINT NOT NULL, + c3 BIGINT NOT NULL, + c4 BIGINT NOT NULL, + PRIMARY KEY (c1) +); +``` + +We want to form a subsharding vindex with 4 bytes from column `c1`, 2 bytes +from column `c2` and 2 bytes from column `c3`, using the `xxhash` hashing +function for each column. The complete vschema would look something like: + +``` +{ + "sharded": true, + "vindexes": { + "t1_multicol": { + "type": "multicol", + "params": { + "column_count": "3", + "column_bytes": "4,2,2", + "column_vindex": "xxhash,xxhash,xxhash" + } + }, + "xxhash": { + "type": "xxhash" + } + }, + "tables": { + "t1": { + "columnVindexes": [ + { + "columns": [ + "c1", + "c2", + "c3" + ], + "name": "t1_multicol" + } + ] + } + } +} +``` + +Now, if we have a sharded Vitess cluster, let us observe the routing when all +columns are provided: + +``` +mysql> explain format=vitess select * from t1 where c1=1 and c2=1 and c3=1; ++----------+-------------+----------+-------------+------------+-----------------------------------------------------+ +| operator | variant | keyspace | destination | tabletType | query | ++----------+-------------+----------+-------------+------------+-----------------------------------------------------+ +| Route | EqualUnique | sharded | | UNKNOWN | select * from t1 where c1 = 1 and c2 = 1 and c3 = 1 | ++----------+-------------+----------+-------------+------------+-----------------------------------------------------+ +1 row in set (0.00 sec) +``` + +This is as expected. Let's see the plans when a subset of columns, +in order of their appearance in the vindex is provided: + +``` +mysql> explain format=vitess select * from t1 where c1=1 and c2=1; ++----------+---------+----------+-------------+------------+------------------------------------------+ +| operator | variant | keyspace | destination | tabletType | query | ++----------+---------+----------+-------------+------------+------------------------------------------+ +| Route | Equal | sharded | | UNKNOWN | select * from t1 where c1 = 1 and c2 = 1 | ++----------+---------+----------+-------------+------------+------------------------------------------+ +1 row in set (0.00 sec) + +mysql> explain format=vitess select * from t1 where c1=1; ++----------+---------+----------+-------------+------------+-------------------------------+ +| operator | variant | keyspace | destination | tabletType | query | ++----------+---------+----------+-------------+------------+-------------------------------+ +| Route | Equal | sharded | | UNKNOWN | select * from t1 where c1 = 1 | ++----------+---------+----------+-------------+------------+-------------------------------+ +1 row in set (0.00 sec) +``` + +Note that the number of shards that these types of queries target. For queries that provide a +subset of the subsharding vindex's columns in the `WHERE` clause the target is +dependent on the structure (byte allocation) of the vindex and the number +of shards in the keyspace. + +Next, let's show that providing no columns scatters (as expected): + +``` +mysql> explain format=vitess select * from t1; ++----------+---------+----------+-------------+------------+------------------+ +| operator | variant | keyspace | destination | tabletType | query | ++----------+---------+----------+-------------+------------+------------------+ +| Route | Scatter | sharded | | UNKNOWN | select * from t1 | ++----------+---------+----------+-------------+------------+------------------+ +1 row in set (0.00 sec) +``` + +Similarly, providing a column (or subset of columns) from the subsharding +vindex that does not include the first column will lead to a scatter: + +``` +mysql> explain format=vitess select * from t1 where c3=1; ++----------+---------+----------+-------------+------------+-------------------------------+ +| operator | variant | keyspace | destination | tabletType | query | ++----------+---------+----------+-------------+------------+-------------------------------+ +| Route | Scatter | sharded | | UNKNOWN | select * from t1 where c3 = 1 | ++----------+---------+----------+-------------+------------+-------------------------------+ +1 row in set (0.00 sec) + +mysql> explain format=vitess select * from t1 where c2=1 and c3=1; ++----------+---------+----------+-------------+------------+------------------------------------------+ +| operator | variant | keyspace | destination | tabletType | query | ++----------+---------+----------+-------------+------------+------------------------------------------+ +| Route | Scatter | sharded | | UNKNOWN | select * from t1 where c2 = 1 and c3 = 1 | ++----------+---------+----------+-------------+------------+------------------------------------------+ +1 row in set (0.00 sec) +``` diff --git a/content/en/docs/19.0/user-guides/vschema-guide/unique-lookup.md b/content/en/docs/19.0/user-guides/vschema-guide/unique-lookup.md new file mode 100644 index 000000000..f0d6743e3 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/unique-lookup.md @@ -0,0 +1,112 @@ +--- +title: Unique Lookup Vindexes +weight: 8 +--- + +Certain application features may require you to point-select orders by their id with a query like this: + +```sql +select * from corder where corder_id=1; +``` + +However, issuing this query to Vitess will cause it to scatter this query across all shards because there is no way to know which shard contains that order id. This would be inefficient if the QPS of this query or the number of shards is too high. + +Vitess supports the concept of lookup vindexes, also known as cross-shard indexes. You can instruct Vitess to create and manage a lookup vindex for the `corder_id` column. Such a vindex needs to maintain a mapping from `corder_id` to the `keyspace_id` of the row, which will be stored in a lookup table. + +This lookup table can be created in any keyspace, and it may or may not be sharded. In this particular case, we are going to create the table in the unsharded product keyspace even though the lookup vindex itself is going to be in the `customer` keyspace: + +```sql +create table corder_keyspace_idx(corder_id bigint, keyspace_id varbinary(10), primary key(corder_id)); +``` + +The primary key is `corder_id`. The unique constraint on `corder_id` makes the Lookup Vindex unique: for a given `corder_id` as input, at most one `keyspace_id` can be produced. It is not necessary to name the column as `corder_id`, but it is less confusing to do so. + +Since the table is not sharded, we have a trivial VSchema addition: + +```json + "corder_keyspace_idx": {} +``` + +We can now instantiate the Lookup Vindex in the VSchema of the `customer` keyspace: + +```json + "corder_keyspace_idx": { + "type": "consistent_lookup_unique", + "params": { + "table": "product.corder_keyspace_idx", + "from": "corder_id", + "to": "keyspace_id" + }, + "owner": "corder" + } +``` + +* The vindex is given a distinctive name `corder_keyspace_idx` because of its specific input parameters. +* The vindex type is `consistent_lookup_unique`. We expect this lookup vindex to yield at most one keyspace id for a given input. The `consistent` qualifier is explained below. +* The `params` section of a Vindex is a set of key-value strings. Each vindex expects a different set of parameters depending on the implementation. A lookup vindex requires the following three parameters: + * `table` should be the name of the lookup table. It is recommended that it is fully qualified. + * The `from` and `to` fields must reference the column names of the lookup table. + * An optional fourth parameter: + + * `batch_lookup`: Set this to `"true"` if you want lookups for key values in the lookup vindex table to be batched (i.e. all values that match to a shard of the lookup backing table will be done in a single query). This can be important if you have queries with multiple point lookup values in the `WHERE` clause (e.g. using `IN`). This is not enabled by default, since it only supports binary equality, i.e. does not take collation into account. You should therefore only use it with lookup vindexes where the `from` key is binary or binary equivalent (e.g. integer or a character field where you are sure that collation matching is not required). Without this option, lookups of multiple values in the shards backing the lookup table will be performed one-by-one, and can have a significant latency overhead if you have a large number of values to lookup per query, relative to your number of shards. +* The `owner` field indicates that `corder` is responsible for populating the lookup table and keeping it up-to-date. This means that an insert into `corder` will result in a corresponding lookup row being inserted in the lookup table, etc. Lookup vindexes can also be shared, but they can have only one owner each. We will later see an example about how to share lookup vindexes. + +{{< info >}} +Since `corder_keyspace_idx` and `corder` are in different keyspaces, any change that affects the lookup column results in a distributed transaction between the `customer` shard and the `product` keyspace. Usually, a two-phase commit (2PC) protocol would need to be used for the distributed transaction. However, the `consistent` lookup vindex utilizes a special algorithm that orders the commits in such a way that a commit failure resulting in partial commits does not result in inconsistent data. This avoids the extra overheads associated with 2PC. +{{< /info >}} + +Finally, we must associate `customer.corder_id` with the lookup vindex: + +```json + "column_vindexes": [{ + "column": "customer_id", + "name": "hash" + }, { + "column": "corder_id", + "name": "corder_keyspace_idx" + }] +``` + +Note that `corder_id` comes after `customer_id` implying that `customer_id` is the Primary Vindex for this table. + +Alternate VSchema DDL: + +```sql +alter vschema add table product.corder_keyspace_idx; +alter vschema on customer.corder add vindex corder_keyspace_idx(corder_id) using consistent_lookup_unique with owner=`corder`, table=`product.corder_keyspace_idx`, from=`corder_id`, to=`keyspace_id`; +``` + +{{< info >}} +An owned lookup vindex (even if unique) cannot be a Primary Vindex because it creates an association against a keyspace id after one has been assigned to the row. The job of computing the keyspace id must therefore be performed by a different unique vindex. +{{< /info >}} + +Bringing up the demo application again, you can now see the lookup table being automatically populated when rows are inserted in `corder`: + +```text +mysql> insert into corder(customer_id, product_id, oname) values (1,1,'gift'),(1,2,'gift'),(2,1,'work'),(3,2,'personal'),(4,1,'personal'); +Query OK, 5 rows affected (0.00 sec) + +mysql> select corder_id, hex(keyspace_id) from corder_keyspace_idx; ++-----------+------------------+ +| corder_id | hex(keyspace_id) | ++-----------+------------------+ +| 1 | 166B40B44ABA4BD6 | +| 2 | 166B40B44ABA4BD6 | +| 3 | 06E7EA22CE92708F | +| 4 | 4EB190C9A2FA169C | +| 5 | D2FD8867D50D2DFE | ++-----------+------------------+ +5 rows in set (0.01 sec) +``` + +And then, issuing a query like `select * from corder where corder_id=1` results in two single-shard round-trips instead of a full scatter. + +### Reversible Vindexes + +Looking at the rows in `corder_keyspace_idx` reveals a few things. We get to now see actual keyspace id values that were previously invisible. We can also notice that two different inputs `1` and `2` map to the same keyspace id `166B40B44ABA4BD6`. In other words, a unique vindex does not necessarily guarantee that two different values yield different keyspace ids. In fact, this is derived from the fact that there are two order rows for customer id `1`. + +Vindexes that do have a one-to-one correspondence between the input value and keyspace id , like `hash`, are known as reversible vindexes: Given a keyspace id, the input value can be back-computed. This property will be used in a later example. + +### Backfill + +To Backfill the vindex on an existing table refer to [Backfill Vindexes](../backfill-vindexes) diff --git a/content/en/docs/19.0/user-guides/vschema-guide/unsharded.md b/content/en/docs/19.0/user-guides/vschema-guide/unsharded.md new file mode 100644 index 000000000..60a39748c --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/unsharded.md @@ -0,0 +1,85 @@ +--- +title: Unsharded Keyspace +weight: 4 +--- + +We are going to start with configuring the `product` table in the unsharded keyspace `product`. The schema file should be as follows: + +```sql +create table product(product_id bigint auto_increment, pname varchar(128), primary key(product_id)); +``` + +`product_id` is the primary key for product, and it is also configured to use MySQL’s `auto_increment` feature that allows you to automatically generate unique values for it. + +We also need to create a VSchema for the `product` keyspace and specify that `product` is a table in the keyspace: + +```json +{ + "sharded": false, + "tables": { + "product": {} + } +} +``` + +The json states that the keyspace is not sharded. The product table is specified in the “tables” section of the json. This is because there are other sections that we will introduce later. + +For unsharded keyspaces, no additional metadata is needed for regular tables. So, their entry is empty. + +Alternate VSchema DDL: + +```sql +alter vschema add table product.product; +``` + +{{< info >}} +If `product` is the only keyspace in the cluster, a vschema is unnecessary. Vitess treats single keyspace clusters as a special case and optimistically forwards all queries to that keyspace even if there is no table metadata present in the vschema. But it is a best practice to provide a full vschema to avoid future complications. +{{< /info >}} + +Bringing up the cluster will allow you to access the `product` table. You can now insert rows into the table: + +```text +$ mysql -h 127.0.0.1 -P 12348 +[snip] +mysql> insert into product(pname) values ('monitor'), ('keyboard'); +Query OK, 2 rows affected (0.00 sec) + +mysql> select * from product; ++------------+----------+ +| product_id | pname | ++------------+----------+ +| 1 | monitor | +| 2 | keyboard | ++------------+----------+ +2 rows in set (0.00 sec) +``` +The insert does not specify values for `product_id`, because we are relying on MySQL’s `auto_increment` feature to populate it. + +You will notice that we did not connect to the `product` database or issue a `use` statement to select it. This is the ‘unspecified’ mode supported by Vitess. As long as a table name can be uniquely identified from the vschemas, Vitess will automatically direct the query to the correct keyspace. + +You can also connect or specify keyspaces as if they were MySQL databases. The following constructs are valid: + +```text +mysql> select * from product.product; ++------------+----------+ +| product_id | pname | ++------------+----------+ +| 1 | monitor | +| 2 | keyboard | ++------------+----------+ +2 rows in set (0.00 sec) + +mysql> use product; +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Database changed +mysql> select * from product; ++------------+----------+ +| product_id | pname | ++------------+----------+ +| 1 | monitor | +| 2 | keyboard | ++------------+----------+ +2 rows in set (0.01 sec) +``` diff --git a/content/en/docs/19.0/user-guides/vschema-guide/vschema_ddl.md b/content/en/docs/19.0/user-guides/vschema-guide/vschema_ddl.md new file mode 100644 index 000000000..b87844d20 --- /dev/null +++ b/content/en/docs/19.0/user-guides/vschema-guide/vschema_ddl.md @@ -0,0 +1,112 @@ +--- +title: VSchema DDL +weight: 30 +--- + +VSchema DDL is an experimental feature that allows users to alter the VSchema by issuing "vschema ddls" directly to vtgate. The `vschema_ddl_authorized_users` flag specifies which users can alter the vschema. + +### SHOW VSCHEMA TABLES + +``` +SHOW VSCHEMA TABLES +``` + +Shows tables in VSchema. + +### SHOW VSCHEMA VINDEXES + +``` +SHOW VSCHEMA VINDEXES +``` + +Shows all vindexes in VSchema. + +### SHOW VSCHEMA VINDEXES FROM tbl_name + +``` +SHOW VSCHEMA VINDEXES [FROM | ON] tbl_name +``` + +Shows vindexes from table `tbl_name` in VSchema. + +### ALTER VSCHEMA ADD TABLE + +``` +ALTER VSCHEMA ADD TABLE {keyspace_name.tbl_name | tbl_name} +``` + +Adds the given table to the VSchema for the current keyspace. + +### ALTER VSCHEMA DROP TABLE + +``` +ALTER VSCHEMA DROP TABLE {keyspace_name.tbl_name | tbl_name} +``` + +Drops the table from the VSchema for the current keyspace. + +### ALTER VSCHEMA CREATE VINDEX + +``` +ALTER VSCHEMA CREATE VINDEX vindex_name USING vindex_type [WITH vindex_option[, vindex_option] ...] + +vindex_option: { + name = value +} +``` + +Creates a vindex with the specified `vindex_type` and `vindex_option`s. + +For the various vindex types and vindex options see [Vindexes documentation](https://vitess.io/docs/17.0/reference/features/vindexes/#predefined-vindexes). + +### ALTER VSCHEMA DROP VINDEX + +``` +ALTER VSCHEMA DROP VINDEX vindex_name +``` + +Drops a vindex from the VSchema. + +### ALTER VSCHEMA ON tbl_name ADD VINDEX + +``` +ALTER VSCHEMA ON tbl_name ADD VINDEX tbl_name.vindex_name (column_name[, column_name] ...) [USING vindex_type] [WITH vindex_option[, vindex_option] ...] +``` + +Adds a vindex for table `tbl_name` and columns `column_name`. + +For the various vindex types and vindex options see [Vindexes documentation](https://vitess.io/docs/17.0/reference/features/vindexes/#predefined-vindexes). + + +### ALTER VSCHEMA ON tbl_name REMOVE VINDEX + +``` +ALTER VSCHEMA ON tbl_name REMOVE VINDEX tbl_name.vindex_name +``` + +Removes a vindex from table `tbl_name`. + + +### ALTER VSCHEMA ADD SEQUENCE + +``` +ALTER VSCHEMA ADD SEQUENCE tbl_name.seq_name +``` + +### ALTER VSCHEMA DROP SEQUENCE + +``` +ALTER VSCHEMA DROP SEQUENCE tbl_name.seq_name +``` + +### ALTER VSCHEMA ON ... ADD AUTO_INCREMENT + +``` +ALTER VSCHEMA ON tbl_name ADD AUTO_INCREMENT column_name USING tbl_name.seq_name +``` + +### ALTER VSCHEMA ON ... DROP AUTO_INCREMENT + +``` +ALTER VSCHEMA ON tbl_name DROP AUTO_INCREMENT +``` diff --git a/content/en/docs/releases/_index.md b/content/en/docs/releases/_index.md index 8cf8add57..27839f67f 100644 --- a/content/en/docs/releases/_index.md +++ b/content/en/docs/releases/_index.md @@ -17,6 +17,9 @@ Each major release is maintained for 1 year. > The latest and current vitess release is v17.0 +### v18.0 +- **Current version:** [v18.0.0-rc1](https://github.com/vitessio/vitess/releases/tag/v18.0.0-rc1) (2023-10-03) + ### v17.0 - **Current version:** [v17.0.2](https://github.com/vitessio/vitess/releases/tag/v17.0.2) (2023-08-18) - **Initial GA release:** [v17.0.0](https://github.com/vitessio/vitess/releases/tag/v17.0.0) (2023-06-27) diff --git a/content/zh/docs/18.0/_index.md b/content/zh/docs/18.0/_index.md index 69d58e050..d877c47bc 100644 --- a/content/zh/docs/18.0/_index.md +++ b/content/zh/docs/18.0/_index.md @@ -1,6 +1,6 @@ --- -title: v18.0 (Development) -description: Under construction, development release. 因为这些文档不维护，所以它们是旧的。你想了解的有关世界上最具扩展性的开源MySQL平台的一切，都在这里 +title: v18.0 (RC) +description: Release Candidate. 因为这些文档不维护，所以它们是旧的。你想了解的有关世界上最具扩展性的开源MySQL平台的一切，都在这里 notoc: true cascade: version: v18.0 diff --git a/content/zh/docs/19.0/_index.md b/content/zh/docs/19.0/_index.md new file mode 100644 index 000000000..2cc54cb95 --- /dev/null +++ b/content/zh/docs/19.0/_index.md @@ -0,0 +1,26 @@ +--- +title: v19.0 (Development) +description: Under construction, development release. 因为这些文档不维护，所以它们是旧的。你想了解的有关世界上最具扩展性的开源MySQL平台的一切，都在这里 +notoc: true +cascade: + version: v19.0 +weight: 81 +--- + +Vitess是一个用于部署、扩展和管理大型MySQL实例集群的数据库解决方案。它可以运行在本地硬件环境、私有云、公用云架构上，效率相差无几。 + +## Vitess 和 MySQL + +Vitess集Mysql数据库的很多重要特性和NoSQL数据库的可扩展性于一体。 Vitess可以帮助您解决各种问题，包括： + +1. 支持您对MySQL数据库进行分片来扩展MySQL数据库，应用程序无需做太多更改。 +2. 从物理机迁移到私有云或公共云。 +3. 部署和管理大量的MySQL实例。 + +## Vitess 数据库驱动 + +Vitess包括使用与本机查询协议兼容的[JDBC](https://github.com/vitessio/vitess/tree/master/java) 和[Go](https://godoc.org/vitess.io/vitess/go) (Golang)数据库驱动。此外，它还实现了[mysql服务器协议](https://dev.mysql.com/doc/internals/en/client-server-protocol.html)，该协议几乎与任何其他语言都兼容。 + +## Vitess 在行动 + +自2011年以来，Vitess一直为YouTube所有的数据库提供服务，现在已被许多企业采用并应用于实际生产。 diff --git a/content/zh/docs/19.0/concepts/_index.md b/content/zh/docs/19.0/concepts/_index.md new file mode 100644 index 000000000..8f294d71e --- /dev/null +++ b/content/zh/docs/19.0/concepts/_index.md @@ -0,0 +1,8 @@ +--- +title: 概念 +description: 学习Vitess核心的概念和术语 +weight: 3 +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} \ No newline at end of file diff --git a/content/zh/docs/19.0/concepts/cell.md b/content/zh/docs/19.0/concepts/cell.md new file mode 100644 index 000000000..c83827835 --- /dev/null +++ b/content/zh/docs/19.0/concepts/cell.md @@ -0,0 +1,12 @@ +--- +title: Cell +description: 数据中心, 可用区域或计算资源组 +--- +一个Cell是指一个网络资源区域，在这个区域里，放置一组服务器或网络基础设施。它通常对应物理部署中的数据中心，有时称为*区域*或者*可用区域*。Cell的主要作用是网络隔离。Vitess可以优雅的处置Cell级别的网络故障，如果有其他的Cell故障并不会影响到当前Cell。 + + +Vitess中的每个Cell里都有一个[本地拓扑服务托管服务集群](../topology-service)，本地拓扑服务负责存储和管理注册在此Cell下的所有网络资源的相关元数据信息。其中包括这个Cell下所有的路由及vttabelt的信息。这样的设计使得Cell更加易于模块化管理，方便拆卸和组装。 + + +vitess支持跨Cell的读写操作，考虑如下情况，假设一个shard有3个实例，1主2从，其中一个master,一个replica，一个rdonly。同样有3个cell, A cell 、 B cell 、C cell,我们可以将master放在A cell， replica放在B cell, rdonly放在C cell。这样，当B cell由于机房故障或者网络故障不能提供服务的时候，我们仍然有master和rdonly提供服务，如果运气不好master节点所在机器或者机房故障，vitess的另一个神器orc可以自动发现deadmaster并进行故障迁移，将replica提升为主。从而实现异地灾备。 + diff --git a/content/zh/docs/19.0/concepts/keyspace-id.md b/content/zh/docs/19.0/concepts/keyspace-id.md new file mode 100644 index 000000000..69f5afdcf --- /dev/null +++ b/content/zh/docs/19.0/concepts/keyspace-id.md @@ -0,0 +1,10 @@ +--- +title: Keyspace ID +--- +*keyspace ID*是用于确定给定行所在的分片的值。 [基于范围的分片]（../../sharding/#key-ranges-and-partitions）是指创建分片，每个分片覆盖特定范围的keyspace ID。 + +使用此技术意味着您可以通过将两个或多个新分片替换为一个给定分片，这些分片组合起来覆盖原始范围的keyspace ID，而不必移动其他分片中的任何记录。 + +keyspace ID本身是使用数据中某些列的函数计算出来的，例如用户ID。 Vitess允许您从各种功能中选择（[vindexes]（../../ schema-management/vschema/））来执行映射规则。这允许您选择适合您业务场景的跨分片数据的最佳分布。 + + diff --git a/content/zh/docs/19.0/concepts/keyspace.md b/content/zh/docs/19.0/concepts/keyspace.md new file mode 100644 index 000000000..622e204fc --- /dev/null +++ b/content/zh/docs/19.0/concepts/keyspace.md @@ -0,0 +1,9 @@ +--- +title: Keyspace +--- + + *keyspace*是逻辑上的数据库，在单片场景下，一个keyspace对应一个MYSQL集群。从Keyspace中读取数据和从一个MYSQL DataBase中读取数据很像。但是根据读取数据时不同的一致性要求，可以从一个master或者从一个replica读取数据。当一个keySpace被sharding成[多分片]（http://en.wikipedia.org/wiki/Shard_(database_architecture))，一个keyspace会对应多个MYSQL database。在这种情况下一个查询会被路由到一个或者多个shard上，这取决于请求的数据所在的位置。 + +从应用程序的角度来看，不管一个keyspace是单分片（1个Mysql集群）还是多分片(多个Mysql集群)，在keyspace上的所有操作，和操作普通MYSQL库没有任何区别，应用感知不到分片的概念。 + + diff --git a/content/zh/docs/19.0/concepts/replication-graph.md b/content/zh/docs/19.0/concepts/replication-graph.md new file mode 100644 index 000000000..6f8a9e0ee --- /dev/null +++ b/content/zh/docs/19.0/concepts/replication-graph.md @@ -0,0 +1,7 @@ +--- +title: Replication Graph +--- + +*replication graph*标识master与其相关replicas间的关系。在master故障切换后，replication graph可以使Vitess将所有replicas指向的新的master,组成新的集群提供服务,保持主从复制。 + + diff --git a/content/zh/docs/19.0/concepts/shard.md b/content/zh/docs/19.0/concepts/shard.md new file mode 100644 index 000000000..f22811c7c --- /dev/null +++ b/content/zh/docs/19.0/concepts/shard.md @@ -0,0 +1,17 @@ +--- +title: Shard +--- + +*shard*是keyspace中的一个mysql集群。分片通常包含一个MySQL主服务器和许多MySQL从服务器。 + +分片中的每个MySQL实例都具有相同的数据（复制延迟情况除外）。从库可用于提供只读流量（最终一致性保证）、执行长时间运行的数据分析工具或执行管理任务（备份，恢复，数据差异对比等等）。 + +unsharded keyspace实际上只有一个分片。 Vitess按照惯例命名shard为“0”。分片时，keyspace有"N"个非重叠数据分片。 + +## Resharding + +Vitess 支持[动态拆分](../../sharding/#resharding),在线上群集实施更改分片数量。这可以是将一个或多个分片分成更小的分片，或者将相邻的分片合并为更大分片。 + +在动态拆分期间，源分片中的数据将复制到目标分片中，开启过滤复制追平数据差异，然后与原始分片进行比较以确保数据完整性。接下来，将实时服务基础结构转移到目标分片，并删除源分片。 + + diff --git a/content/zh/docs/19.0/concepts/tablet.md b/content/zh/docs/19.0/concepts/tablet.md new file mode 100644 index 000000000..af94c1942 --- /dev/null +++ b/content/zh/docs/19.0/concepts/tablet.md @@ -0,0 +1,16 @@ +--- +title: Tablet +--- + +*tablet*是`mysqld`进程和相应的`vttablet`进程的组合，通常在同一台机器上运行。 + +每个tablet都分配了*tablet type*，用于指定当前table的角色。 + +## Tablet Types + +* **master** - *master* tablet是其所在分片的MySQL主. +* **replica** - 一个有资格被提升为*master*的MySQL slave。通常，replica角色用于提供面向用户的实时请求服务（例如来自网站的前端请求）。 +* **rdonly** - 一个无法升级为*master*的MySQL slave。通常，这些用于后台处理作业，例如进行备份，将数据转储到其他系统，重度分析查询，MapReduce和重新分片。 +* **backup** - 已经停止复制的tablet，因此可以用作为此分片上传备份数据。当数据备份完成后，它将恢复binlog复制并恢复到其先前的tablet类型。 +* **restore** - tablet启动时没有数据，正在从最新备份恢复时的状态。这是一个过渡的状态，当tablet拉取备份并恢复完成后，它会从备份数据中的GTID位置开始追平数据延迟，并成为*replica*或*rdonly*（与Tablet做备份恢复之前的状态保持一致）。 +* **drained** - 由Vitess后台程序用到的tablet状态，例如用于重新分片时候，rdonly tablet会变成drained状态，在重新分片过程结束之后，tablet会重新被置回rdonly状态。 \ No newline at end of file diff --git a/content/zh/docs/19.0/concepts/topology-service.md b/content/zh/docs/19.0/concepts/topology-service.md new file mode 100644 index 000000000..95ad2ab13 --- /dev/null +++ b/content/zh/docs/19.0/concepts/topology-service.md @@ -0,0 +1,33 @@ +--- +title: topology-service +description: 拓扑或分布式锁服务 +--- + +[*拓扑服务*](../../user-guides/topology-service)是一个包含服务器信息、分片方案和主从信息的元数据信息存储服务。拓扑服务是基于一致性存储方案来实现数据一致性， 例如：zookeeper和etcd。 用户可以通过使用vtctl（命令行）和vtctld（web）访问拓扑服务。 + + +Vitess使用插件系统来支持各种后端服务用于存储拓扑数据，为这些后端服务提供式分布式一致性键值存储。默认情况下[本地示例](../../tutorials/local)使用ZooKeeper插件，而[Kubernetes示例](../../tutorials/kubernetes)使用etcd。 + +使用拓扑服务有以下几个原因： + +*Vitess*将tablets作为一个集群进行协调和管理。 +*Vitess*使用拓扑服务用作服务发现，tablets会注册到拓扑服务中，Vitess从而知道一个查询请求路由到何处。 +*拓扑服务存储数据库管理员设定的Vitess配置，该配置是群集中服务器共需的，并且必须保证持久性。 + + +Vitess集群具有一个全局拓扑服务，并且每个cell中具有本地拓扑服务。由于*cluster*是一个重载项，并且一个Vitess集群通过每个Vitess集群都有自己的全局拓扑服务来区分，我们将每个Vitess集群称为**toposphere**。 + +## 全局拓扑服务 + +全局拓扑用以存储不频繁更改的Vitess范畴内的数据。具体来说，它包含有keyspaces和shard的数据以及每个shard的扮演master角色tablet的别名。 + +全局拓扑用于某些操作，包括reparent(重新设置master)和(resharding)重新拆分。按照设计原则，全局拓扑服务器使用不会太频繁。 + +为了避免一个cell down掉影响到全局拓扑的服务，全局拓扑服务需要在各个cell中部署有节点，确保有足够的节点以维持仲裁，提供服务。 + +## 本地拓扑服务 + +每个本地拓扑里存储了与其自己所属cell的相关信息。具体来说，它包含cell中所有tablet的数据，该cell的keyspace graph、replication graph也存储在本地拓扑里。 + +本地拓扑服务非常重要，它必须工作正常以供Vitess发现tablets的动向，在tablets注册和退出注册后能够及时的调整路由。值得注意的是，在提供查询的关键路径中并不涉及到调用拓扑服务，所以，及时本地拓扑服务暂时不能提供服务，仍然不影响Vitess提供正常的查询服务。 + diff --git a/content/zh/docs/19.0/concepts/vschema.md b/content/zh/docs/19.0/concepts/vschema.md new file mode 100644 index 000000000..f41dd36e8 --- /dev/null +++ b/content/zh/docs/19.0/concepts/vschema.md @@ -0,0 +1,11 @@ +--- +title: VSchema +--- + +[VSchema]（../../schema-management/vschema/）用于描述如何在keyspace和分片中存储数据。Vschma用于带路由键的SQL查询，也用于拆分分片操作。 + +对于keyspace，你可以指定它是否分片。对于分片的keyspace来说，你可以指定每张表的vindexes(路由键)。 + +Vitess支持[全局自增键](../../schema-management/vschema/#sequences) +可以用来生成像MySQL自动序列一样的全局唯一ID。 你可以设定表的某列是全局自增的列。写入时不加此列写入，VTGate会使用全局唯一自增功能为其生成全局唯一ID。 + diff --git a/content/zh/docs/19.0/contributing/_index.md b/content/zh/docs/19.0/contributing/_index.md new file mode 100644 index 000000000..a51ea1bc6 --- /dev/null +++ b/content/zh/docs/19.0/contributing/_index.md @@ -0,0 +1,86 @@ +--- +title: 贡献Vitess +description: 我们热爱所有参与贡献的人，这篇文章将描述您如何参与到贡献Vitess中来 +weight: 6 +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} + +什么，听说您想对vitess作出贡献？这简直太棒了！ + +过去的一段时间，我们审查并接受了许多外部贡献。比如Java JDBC驱动程序，PHP PDO驱动程序或以及vtgate v3改进。 + +我们期待来自您的任何贡献！在您开始做出更大贡献之前，请务必先与我们联系，与我们一起讨论一下您的计划。 + +这个页面描述了新贡献者如何熟悉Vitess和编程语言Go。 + + +## 学习 Go + +Vitess是[谷歌编程语言Go](https://golang.org/)的早期吃螃蟹的人. + +与C++或Java比，我们喜欢它的简洁；与Python比，我们喜欢它的性能表现。 + +如果您想对我们的服务器代码作出贡献，您需要对Go有一定了解。如果您并未有太多的Go经验，我们建议您阅读以下资源。 + +### Go 之旅 + +https://tour.golang.org/ + + +Go之旅是一个基于浏览器的教程，它解释了Go编程语言的基本概念。 +它是交互式的，即您可以更改并运行右侧的所有示例。 +后面的步骤也有特定的练习，你可以尝试自己完成编码。 +渐进式的学习使您的学习过程变得很有趣，而且您会愈发的体会到编写Go代码是多么简单。 + +### Go 可读性 + +在Google内部，代码审核需要额外的“可读性”审核。 + +可读性审阅者确保被审阅者编写惯用代码并遵循编程语言的样式指南。 + +虽然没有Go风格指南，但Go社区中有一系列建议，这些建议加起来就是隐式风格指南。为了确保您正在编写惯用风格的Go代码，请阅读以下文档： + + +* Go 可读性幻灯片 https://talks.golang.org/2014/readability.slide + * 通过许多具体的例子来了解Go的可读性。 +* "高效的 Go": https://golang.org/doc/effective_go.html + * Recommendations for writing good Go code. +* Go 代码审阅注释: https://github.com/golang/go/wiki/CodeReviewComments + * 最接近风格指南的参考资料。 + +### 其他资源 + +如果您不确定Go的行为或语法，我们建议您在规范中查找： https://golang.org/ref/spec +它写得很好，易于理解 + +### 欣赏 Go + +使用Go几周之后，我们希望您能像我们一样开始热爱Go。 + +在我们看来，谷歌acapella乐队ScaleAbility的歌曲“Write in Go”完美地捕捉了Go的特别之处。观看它，享受你学到的Go: www.youtube.com/watch?v=LJvEIjRBSDA + +## 学习 Vitess + +在深入了解Vitess代码库之前，请务必先熟悉Vitess架构，并尝试本地跑起来Vitess: + +* 可以先看看[What is Vitess](../overview/whatisvitess) 页面, 尤其是架构部分要深入理解。 + +* 接下来学习[Vitess concepts](../overview/concepts) 部分和[Sharding](../sharding) 概念。 + + * 我们建议您抽空看看 [latest presentations](../resources/presentations)。这些presentations包含了许多插图，有助于帮助您了解Vitess的详细工作原理。 + + * 在您完成了上述学习之后，尝试回答以下问题 (单击展开可以查看答案): +
    + + 一个keyspace有256个基于范围的分片，请问第一个，第二个和最后一个分片的名称是什么？ + + -01, 01-02, ff- +
    + +* 详细了解 [Vitess Kubernetes tutorial](../get-started/kubernetes) 部分。 + + * 在阅读教程的同时，别忘了经常回顾 [架构部分](../overview/architecture/#architecture) ，想一想Kubernetes中的哪部分流程与架构图中的哪部分能够匹配上？ + + diff --git a/content/zh/docs/19.0/contributing/build-from-source.md b/content/zh/docs/19.0/contributing/build-from-source.md new file mode 100644 index 000000000..bc31684f2 --- /dev/null +++ b/content/zh/docs/19.0/contributing/build-from-source.md @@ -0,0 +1,271 @@ +--- +title: 从源码构建 +description: 如何从本机构建、开发及测试Vitess +weight: 1 +featured: true +--- + + + +{{< info >}} +如果您遇到问题或有疑问，我们建议您在我们的[Slack 频道](https://vitess.slack.com)上发帖，点击右上角的Slack图标加入。这是一个非常活跃的社区论坛，也是与其他用户互动的好地方。当然，你也可以加入微信群组**vitess中国**寻求帮助，这里的人们也很热心，时刻准备好回答您的任何问题。 +{{< /info >}} + +## 源码编译 + +以下部分介绍了在Linux和macOS上手动构建Vitess的过程。如果您是Vitess的新手，建议先从[本地部署](../../tutorials/local) 指南开始。 + +### 安装依赖 + +我们目前正在Ubuntu 14.04（Trusty）和Debian 8（Jessie）上定期测试Vitess。 macOS 10.11（El Capitan）及以上版本也可以使用。安装说明[如下所示](#macos). + +#### Ubuntu and Debian + + Vitess依赖如下软件和库: + +1. [Install Go 1.15+](http://golang.org/doc/install). + +2. Install MySQL: +```bash +# Apt based +sudo apt-get install mysql-server +# Yum based +sudo yum install mysql-server +``` + +_Vitess支持MySQL 5.6+和MariaDB 10.0+。我们建议使用MySQL 5.7。_ + +3. 卸载或者禁用 [AppArmor](https://wiki.ubuntu.com/AppArmor)。某些版本的MySQL带有Vitess工具尚未识别的默认AppArmor配置。当Vitess通过`mysqlctl`工具初始化MySQL实例时，这会导致各种权限失败。这仅在测试环境中存在问题。如果在生产中需要AppArmor，则可以在不通过`mysqlctl`的情况下适当地配置MySQL实例。 + + ```sh + sudo service apparmor stop + sudo service apparmor teardown # safe to ignore if this errors + sudo update-rc.d -f apparmor remove + ``` + + 重新启动以确保完全禁用AppArmor。 + +4. 安装 [etcd v3.0+](https://github.com/coreos/etcd/releases). 请记住在您的路径中包含`etcd`命令。 + + 我们将使用ectd作为[拓扑服务](../../overview/concepts)。 Vitess还包括对[ZooKeeper](https://zookeeper.apache.org) 和 [Consul](https://www.consul.io/)的内置支持。 + +5. 安装构建和运行Vitess所需的以下工具： + + - make + - automake + - libtool + - python-dev + - python-virtualenv + - python-mysqldb + - libssl-dev + - g++ + - git + - pkg-config + - bison + - curl + - unzip + + 可以使用以下apt-get命令安装它们 + ```sh + $ sudo apt-get install make automake libtool python-dev python-virtualenv python-mysqldb libssl-dev g++ git pkg-config bison curl unzip + ``` + +#### Mac OS + +1. [安装 Homebrew](http://brew.sh/)。如果您的`/usr/local`目录不为空且尚未使用Homebrew，则需要运行以下命令： + + ```sh + sudo chown -R $(whoami):admin /usr/local + ``` + +2. 您可以通过安装[Xcode](https://developer.apple.com/xcode/)(推荐)或 [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)来满足Vitess的依赖关系。如果没有安装Xcode，那么采用如下命令安装pkg-config + + ```sh + brew install pkg-config + ``` + +3. 安装 [etcd v3.0+](https://github.com/coreos/etcd/releases). 将`etcd` 命令放置在您的环境变量路径中。 + + 我们将使用ectd作为[拓扑服务](../../overview/concepts)。Vitess 同时还包括对 [ZooKeeper](https://zookeeper.apache.org) 和 [Consul](https://www.consul.io/) 的内置支持。 + + +4. 运行如下命令: + + ```sh + brew install go ant automake libtool python git bison curl wget mysql57 + pip install --upgrade pip setuptools + pip install virtualenv + pip install MySQL-python + pip install tox + ``` + +5. Vitess引导程序脚本对go运行时环境进行了一些检查，因此建议在您在 `~/.profile`, `~/.bashrc`, `~/.zshrc`, 或者`~/.bash_profile`文件中包含如下命令: + + ```sh + export PATH="/usr/local/opt/mysql@5.7/bin:$PATH" + export PATH=/usr/local/go/bin:$PATH + export GOROOT=/usr/local/go + ``` + +6. 要使Vitess主机名能够正常解析，需要在/etc/hosts文件中添加一个新的映射关系，其中包含计算机的当前LAN IP地址（最好是IPv4）和当前主机名，您可以通过在终端键入'hostname'获得主机名。 + 将如下命令放到 [强制使用 Go DNS 解析器](https://golang.org/doc/go1.5#net) `~/.profile` 或者 `~/.bashrc` 或者 `~/.zshrc`文件中也是一个好主意: + + +```sh + export GODEBUG=netdns=go + ``` + +## 编译 Vitess + +1. cd到你想cloen vitess源码的目录，clone之。完成后进入到 `src/vitess.io/vitess` 目录中。 + + ```sh + cd $WORKSPACE + git clone https://github.com/vitessio/vitess.git \ + src/vitess.io/vitess + cd src/vitess.io/vitess + ``` + +2. 设置 `MYSQL_FLAVOR`: +```sh +# It is recommended to use MySQL56 even for MySQL 5.7 and 8.0. For MariaDB you can use MariaDB: +export MYSQL_FLAVOR=MySQL56 +``` + +3. 如果你的MYSQL数据库安装在 `/usr/bin`之外的位置， 请将`VT_MYSQL_ROOT` v变量设置为Mysql安装的根目录: + + ```sh + # 通过tar包安装的设置参考 + export VT_MYSQL_ROOT=/usr/local/mysql + + # 通过Homebrew安装的设置参考 + export VT_MYSQL_ROOT=/usr/local/opt/mysql@5.7 + ``` + + 请注意上述命令设置生效的前提 `mysql` 可执行文件在 `/usr/local/opt/mysql@5.7/bin/mysql`这里。 + +4. 运行 `mysqld --version` 确保你使用的是 MySQL 5.7版本。 + +5. 使用以下命令构建Vitess。请注意，`bootstrap.sh`脚本需要下载一些依赖项。如果您的计算机需要代理才能访问Internet，则需要设置常用的环境变量 (e.g. `http_proxy`, `https_proxy`, `no_proxy`). + + 运行 boostrap.sh 脚本: + + ```sh + BUILD_TESTS=0 ./bootstrap.sh + ### example output: + # skipping zookeeper build + # go install golang.org/x/tools/cmd/cover ... + # Found MariaDB installation in ... + # creating git pre-commit hooks + # + # source dev.env in your shell before building + ``` + + ```sh + # Remaining commands to build Vitess + source ./dev.env + make build + ``` + +#### 编译遇到问题怎么办 + +{{< info >}} +如果您遇到问题或有疑问，我们建议您在我们的[Slack 频道](https://vitess.slack.com)上发帖，点击右上角的Slack图标加入。这是一个非常活跃的社区论坛，也是与其他用户互动的好地方。当然，你也可以加入微信群组**vitess中国**寻求帮助，这里的人们也很热心，时刻准备好回答您的任何问题。 +{{< /info >}} + +##### Python 报错 + +端到端测试套件目前需要Python 2.7。我们正在努力消除这种依赖关系，你也可以在Docker中运行测试。MySQL 5.7容器包含如下依赖项 + +```bash +make docker_test flavor=mysql57 +``` + +##### Node 已存在, port 报错 + +测试过程失败可能会导致一堆不相关的进程。如果使用默认设置，则可以使用以下命令识别并终止这些进程： + + +```sh +pgrep -f -l '(vtdataroot|VTDATAROOT)' # 展示 Vitess 相关进程 +pkill -f '(vtdataroot|VTDATAROOT)' # 干掉 Vitess 相关进程 +``` + +##### 太多建立到MySQL的连接, 其他超时报错 + +此错误可能意味着您的磁盘太慢。如果你用不起SSD，可以尝试[针对ramdisk进行测试](https://github.com/vitessio/vitess/blob/master/doc/TestingOnARamDisk.md). + +##### tablet连接拒绝， MySQL socket 找不到等问题 + +这些错误可能表示当尝试分配更多RAM时，计算机耗尽RAM并且服务器崩溃。一些较重的测试需要高达8GB的RAM。 + + +##### 硬盘资源耗尽 + +一些较大的测试在磁盘上使用高达4GB的临时空间。 + +##### 文件打开过多 + +ome Linux发行版附带的默认文件描述符限制对于数据库服务器而言太低。此问题可能会显示为数据库因“太多打开文件”消息而崩溃。检查系统范围的file-max设置以及用户特定的ulimit值。我们建议将它们设置在100K以上是安全的。确切的过程可能因您的Linux发行版而异。 + +## 启动单分片集群 + +你可以使用本地测试脚本`101_initial_cluster.sh` 快速启动一个单分片Vitess集群，命令如下： + +``` sh +cd examples/local +./101_initial_cluster.sh +``` + +### 验证集群工作是否正常 + +如果集群工作正常，您应该看到以下状态： + +``` sh +$ pgrep -fl vtdataroot +5451 zksrv.sh +5452 zksrv.sh +5453 zksrv.sh +5463 java +5464 java +5465 java +5627 vtctld +5762 mysqld_safe +5767 mysqld_safe +5799 mysqld_safe +10162 mysqld +10164 mysqld +10190 mysqld +10281 vttablet +10282 vttablet +10283 vttablet +10447 vtgate +``` + +您现在应该可以使用以下命令连接到群集： + +``` sh +$ mysql -h 127.0.0.1 -P 15306 +Welcome to the MySQL monitor. Commands end with ; or \g. +mysql> show tables; ++-----------------------+ +| Tables_in_vt_commerce | ++-----------------------+ +| corder | +| customer | +| product | ++-----------------------+ +3 rows in set (0.01 sec) +``` + +您还可以使用以下URL浏览到vtctld控制台： + +``` +http://localhost:15000 +``` + +### 下一步的工作 + +恭喜！您现在已启动并运行本地vitess群集。您可以按照以下步骤完成其他练习 [Run Vitess Locally](../../tutorials/local)。 + +笔者在Mac上也尝试安装了一次Vitess，大家也可以参考下，附上链接如下 : [Vitess build on Mac](https://www.jianshu.com/p/fb1b1007a095) diff --git a/content/zh/docs/19.0/contributing/code-reviews.md b/content/zh/docs/19.0/contributing/code-reviews.md new file mode 100644 index 000000000..f3f3b52f6 --- /dev/null +++ b/content/zh/docs/19.0/contributing/code-reviews.md @@ -0,0 +1,63 @@ +--- +title: 代码审查 +--- + +每个GitHub的pull请求必须经过代码审查并获得批准才能合并到主分支中。 + + +## 都审查点儿啥 + +作者和参与评审的人都需要回答以下共性的问题： + +* 此次修改是否与现有设计匹配，是否解决了现存的一个BUG？ +* 此次修改是否有适当的单元测试？所有更改都应该增加覆盖范围。当单元测试覆盖不可能时，我们至少需要集成测试覆盖。 +* Is this change going to log too much? (Error logs should only happen when the component is in bad shape, not because of bad transient state or bad user queries) +这项更改会记录太多日志吗？（错误日志只应在组件内部发生异常时记录，而不是由于错误的瞬态状态或错误的用户查询） +* 此更改是否符合我们的编码约定/样式？Linter运行是否正常？ +* 这符合我们目前的模式吗？示例包括RPC模式，使用Context的Retries / Waits / Timeouts模式 ... + +此外，我们建议每一位作者在提交评论之前都要仔细阅读自己的评论，并检查您是否遵循下面的建议。在提交之前，我们通常在浏览`git diff --cached` 时检查这些类型的内容。 + +* 检查差异，就仿佛你是审查员 + * 检查是否签入了本不该签入的文件?（临时/生成的文件）。 + * 仅限谷歌：删除谷歌机密信息（如内部URL）。 + * 查找调试时添加的临时代码/注释。 + * 示例: fmt.Println("AAAAAAAAAAAAAAAAAA") + * 查找缩进中的不一致。 + * 除go外，所有内容都使用2个空格。 + * 在Go中，只需使用goimports。 + +* 提交消息格式: + * ``` + : 这是对更改的简短描述。 + + 如有必要，后面会有更多的句子，例如解释变化的意图、它如何适应更大的图景或它具有的含义（例如，系统中的其他部分必须进行调整）。 + + 有时，此消息还可以包含更多的参考资料，例如基准数字，以证明为什么以这种方式实施更改。 + ``` +* Comments + * `// `后面最好写个完整的句子 + * `//`后面带个空格. + +在审核期间，请确保您处理所有评论。点击图标（reviewable.io）标注完成或者回复“完成”。 （GitHub Review）将评论标记为已解决。当它准备好合并时，应该有0个未解决的讨论。 + +## 指定 Pull 请求 + +如果您想将评论发送给特​​定的一组队友，请将其添加为受让人（pull request的右侧）他们会收到邮件。 + +在讨论过程中，您还可以 *@username* ，他们也会收到一封电子邮件。 + +如果您想要收到通知，即使您没有被提及，也可以转到[repository page](https://github.com/vitessio/vitess) 点击 *Watch*. + +## 同意 Pull 请求 + +作为审阅者，您可以通过两种方式批准Pull请求： + +* 通过GitHub的新代码审查系统批准Pull请求 + +* 回复评论，其中包含单词 *LGTM* (Looks Good To Me 我觉得没问题) + +## 合并 Pull 请求 + +PR在获得批准并且Travis测试通过后，Vitess团队将合并您的Pull请求。 + diff --git a/content/zh/docs/19.0/contributing/github-workflow.md b/content/zh/docs/19.0/contributing/github-workflow.md new file mode 100644 index 000000000..9332029aa --- /dev/null +++ b/content/zh/docs/19.0/contributing/github-workflow.md @@ -0,0 +1,135 @@ +--- +title: GitHub 工作流程 +--- + +如果您是Git和GitHub的新手，我们建议您阅读此页面。否则，您可以跳过它。 + +我们的GitHub工作流程是一个所谓的三角工作流程： + +visualization of the GitHub triangular workflow + +*Image Source:* https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows + + + +这个托管的代码仓库我们称为*upstream*。 +您可以从我们的上游代码仓库克隆一份代码，并在其中开发和提交您的更改（在上图中显示为*local*）。然后将更改推送到您forked代码仓库（*origin*）并向我们发送pull请求 +。最后，我们将把你的pull请求合并回*upstream*代码仓库。 + +## Remotes + +您从您的fork代码仓库中clone一份代码, `origin` remote +应该显示成这样: + +``` +$ git remote -v +origin git@github.com:/vitess.git (fetch) +origin git@github.com:/vitess.git (push) +``` + +为了帮助您保持fork仓与主仓同步，添加一个`upstream`远程 + +``` +$ git remote add upstream git@github.com:vitessio/vitess.git +$ git remote -v +origin git@github.com:/vitess.git (fetch) +origin git@github.com:/vitess.git (push) +upstream git@github.com:vitessio/vitess.git (fetch) +upstream git@github.com:vitessio/vitess.git (push) +``` + +同步你的本地`master`分支，执行以下操作： + +``` +$ git checkout master +(master) $ git pull upstream master +``` + +注意：在上面的示例输出中，我们使用`(master)`前缀提示符， +强调命令必须从分支`master`运行。 + +有一个小技巧，您可以不写`upstream master`，只运行`git pull`命令。前提是您设置了`master`分支跟踪到`vitessio/vitess`分支。如下命令所示： + +``` +(master) $ git branch --set-upstream-to=upstream/master +``` + +现在，以下命令同步您的本地`master`分支: + +``` +(master) $ git pull +``` + +## 主题分支 + +在开始处理更改之前，请创建主题分支： + +``` +$ git checkout master +(master) $ git pull +(master) $ git checkout -b new-feature +(new-feature) $ # You are now in the new-feature branch. +``` + +尝试在完成它们的过程中分批次逐步提交，并在每次的提交更改时附上提交消息注明更改内容。 +有关更多指导，请参阅[代码审查页面](../code-reviews)。 + +当你在一个包中做出修改的时候，你可以在该包中运行`go test`来进行单元测试验证您的修改是否有效。 + +当你准备测试整个系统的时候，从Git tree根目录运行整套测试体系，运行 `make +test` + +如果尚未安装`make test`的所有依赖项，则还可以观察Travis CI测试结果。 +CI 在您提交pull request时候自动执行，你可以等待并观察CI是否顺利通过，如果有问题，CI会跑不过，您可以根据CI的错误提示定位问题，不方便的一点是CI的执行过程很长，您需要耐心等待。 + +## 交付你的工作 + +运行`git commit`时，使用`-s`选项添加Signed-off-by行。 + +这是[the Developer Certificate of Origin](https://github.com/apps/dco)所必须的要求。 + +## 发送 Pull 请求 + +将您的分支推送到代码仓（并将其设置为使用`-u`进行跟踪): + +``` +(new-feature) $ git push -u origin new-feature +``` + +您可以从`git push`中省略`origin`和`-u new-feature`参数,只需运行如下两个Git命令进行配置更改： + +``` +$ git config remote.pushdefault origin +$ git config push.default current +``` + +第一个设置可以避免每次输入`origin`。而第二个设置，Git假设GitHub端的远程分支 +与您的本地分支同名。 + +在此更改之后，您可以运行不带参数的`git push`： + +``` +(new-feature) $ git push +``` + +转到[repository 页面](https://github.com/vitessio/vitess) ,将会提示您从最近推送的分支创建一个Pull请求。 +您也可以 [手动选择分支](https://github.com/vitessio/vitess/compare). + +## 解决变更 + + +如果您需要根据代码审阅者的建议进行代码修复，只需要在此分支上完成修改后再次提交，然后推送即可： + +``` +$ git checkout new-feature +(new-feature) $ git commit +(new-feature) $ git push +``` + +一个提交请求只反映出您所在主题分支的变化，和主分支无关。 + +一旦您的提交请求被合并后： + +* 关闭GitHub问题（如果没有自动关闭） +* 删除您的本地主题分支（`git branch -d new-feature`） + diff --git a/content/zh/docs/19.0/faq/_index.md b/content/zh/docs/19.0/faq/_index.md new file mode 100644 index 000000000..a67c01ec5 --- /dev/null +++ b/content/zh/docs/19.0/faq/_index.md @@ -0,0 +1,84 @@ +--- +title: FAQ +description: Frequently Asked Questions about Vitess +weight: 8 +featured: true +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} + +## Does the application need to know about the sharding scheme underneath Vitess? + +The application does not need to know about how the data is sharded. This information is stored in a VSchema which the VTGates use to automatically route your queries. This allows the application to connect to vitess and use it as if it’s a single giant database server. + +## Can I address a specific shard if I want to? + +If necessary, you can access a specific shard by connecting to it using the shard specific database name. For a keyspace ks and shard -80, you would connect to ks:-80. + +## How do I choose between master vs. replica for queries? + +You can qualify the keyspace name with the desired tablet type using the @ suffix. This can be specified as part of the connection as the database name, or can be changed on the fly through the USE command. + +For example, `ks@master` will select `ks` as the default keyspace with all queries being sent to the master. Consequently `ks@replica` will load balance requests across all `REPLICA` tablet types, and `ks@rdonly` will choose `RDONLY`. + +You can also specify the database name as `@master`, etc, which instructs Vitess that no default keyspace was specified, but that the requests are for the specified tablet type. + +If no tablet type was specified, then VTGate chooses its default, which can be overridden with the `-default_tablet_type` command line argument. + +## There seems to be a 10,000 row limit per query. What if I want to do a full table scan? + +Vitess supports different modes. In OLTP mode, the result size is typically limited to a preset number (10,000 rows by default). This limit can be adjusted based on your needs. + +However, OLAP mode has no limit to the number of rows returned. In order to change to this mode, you may issue the following command before executing your query: + +```shell +set workload='olap' +``` +You can also set the workload to `dba mode`, which allows you to override the implicit timeouts that exist in vttablet. However, this mode should be used judiciously as it supersedes shutdown and reparent commands. + +The general convention is to send OLTP queries to `REPLICA` tablet types, and OLAP queries to `RDONLY`. + +## Is there a list of supported/unsupported queries? + +The list of unsupported constructs is currently in the form of test cases contained in [this test file](https://github.com/vitessio/vitess/blob/b2b3aeb7cf5316eeedbe667fecaa91b1c34a6cea/go/vt/vtgate/planbuilder/testdata/unsupported_cases.txt). However, contrary to the test cases, there is limited support for SET, DDL and DBA constructs. This will be documented in greater detail soon. Until then, [this test file](https://github.com/vitessio/vitess/blob/b2b3aeb7cf5316eeedbe667fecaa91b1c34a6cea/go/vt/vtgate/planbuilder/testdata/unsupported_cases.txt) serves as the canonical source of information on unsupported queries. Do also check on the [Vitess Slack channel](https://vitess.slack.com) (click [here](https://vitess.io/slack) to join) to ask our friendly community about other queries you have in mind. + +## If I have a log of all queries from my app. Is there a way I can try them against vitess to see how they’ll work? + +Yes. The [vtexplain](../vtexplain) tool can be used to preview how your queries will be executed by vitess. It can also be used to try different sharding scenarios before deciding on one. + +## Does the Primary Vindex for a tablet have to be the same as its Primary Key. + +It is not necessary that a Primary Vindex be the same as the Primary Key. In fact, there are many use cases where you would not want this. For example, if there are tables with one-to-many relationships, the Primary Vindex of the main table is likely to be the same as the Primary Key. However, if you want the rows of the secondary table to reside in the same shard as the parent row, the Primary Vindex for that table must be the foreign key that points to the main table. A typical example is a user and order table. In this case, the order table has the `user_id` as a foreign key to the `id` of the user table. The `order_id` may be the primary key for `order`, but you may still want to choose `user_id` as Primary Vindex, which will make a user's orders live in the same shard as the user. + +## How do I connect to vtgate using mysql protocol? + +If you look at the example [vtgate-up.sh](https://github.com/vitessio/vitess/blob/master/examples/local/vtgate-up.sh) script, you'll see the following lines: + +```shell +-mysql_server_port $mysql_server_port \ +-mysql_server_socket_path $mysql_server_socket_path \ +-mysql_auth_server_static_file "./mysql_auth_server_static_creds.json" \ +``` + +In that example, vtgate accepts mysql connections on port 15306, and the authentication info is stored in the json file. So, you should be able to connect to it using the following command: + +```shell +mysql -h 127.0.0.1 -P 15306 -u mysql_user --password=mysql_password +``` + +## Can I override the default db name from vt_xxx to my own? + +Yes. You can start vttablet with the `-init_db_name_override` command line option to specify a different db name. There is no downside to performing this override. + +## I cannot start a cluster, and see these errors in the logs: Could not open required defaults file: /path/to/my.cnf + +Most likely this means that apparmor is running on your server and is preventing vitess processes from accessing the my.cnf file. The workaround is to uninstall apparmor: + +```shell +sudo service apparmor stop +sudo service apparmor teardown +sudo update-rc.d -f apparmor remove +``` + +You may also need to reboot the machine after this. Many programs automatically install apparmor, so you may need to uninstall again. diff --git a/content/zh/docs/19.0/get-started/_index.md b/content/zh/docs/19.0/get-started/_index.md new file mode 100644 index 000000000..e0a6415c3 --- /dev/null +++ b/content/zh/docs/19.0/get-started/_index.md @@ -0,0 +1,10 @@ +--- +title: 入门 +description: 在你最喜爱的平台上部署Vitess +weight: 2 +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} + +Vitess支持在以上平台上进行二进制部署。 如果你对如何构建二进制文件很感兴趣，或者想对vitess做贡献。可以参考[从源码编译](../contributing)。 diff --git a/content/zh/docs/19.0/get-started/kubernetes.md b/content/zh/docs/19.0/get-started/kubernetes.md new file mode 100644 index 000000000..1c4f3924f --- /dev/null +++ b/content/zh/docs/19.0/get-started/kubernetes.md @@ -0,0 +1,843 @@ +--- +title: Kubernetes上跑Vitess +weight: 3 +featured: true +--- + +*下面的示例将使用一个简单的commerce数据库来说明vitess如何将您从一个数据库扩展到一个完全分布式和分片的集群。这是一个相当常见的场景，它适用于电子商务之外的许多用例。* + +随着公司的发展壮大，他们经常会面临这样一个问题：交易数据库中的数据量显著增加。数据大小急剧增加可能导致查询延迟、可管理性变差等影响性能的问题。本教程演示了Vitess如何与Kubernetes一起使用，通过利用分布式系统的水平分片来缓解系统在大规模数据下的数据查询性能问题。 + +### 先决条件 + +在我们开始之前，让我们先了解一些事情。 + +{{< info >}} +示例设置已调整为在Minikube上运行。但是，您应该可以在自己的Kubernetes集群上尝试此操作。如果这样做，您可能还想删除一些Minikube特定的资源设置（如下所述）。 +{{< /info >}} + +* [下载 Vitess](https://github.com/vitessio/vitess) +* [安装 Minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) +* 启动Minikube引擎：`minikube start --cpus = 4 --memory = 5000`。请注意其他资源要求。为了完成所有用例，将启动许多vttablet和MySQL实例。这些需要比Minikube使用的默认值更多的资源。 +* [安装 etcd 管理端](https://github.com/coreos/etcd-operator/blob/master/doc/user/install_guide.md) +* [安装 helm](https://docs.helm.sh/using_helm/) +* 完成安装后, 运行 `helm init` + +### 可选操作 + +* 在Ubuntu上安装Mysql客户端: `apt-get install mysql-client` +* 安装 vtctlclient + * 安装 go 1.11+ + * `go get vitess.io/vitess/go/cmd/vtctlclient` + * vtctlclient 将安装在目录 `$GOPATH/bin/` + +## 启动单片keyspace集群 + +你google了一通keyspace，却发现了很多关于NoSQL的东西。这TM是怎么回事？虽然这会花费你几个小时的时间，但是在仔细翻看vitess的古老卷轴之后，你会发现，原来在未分片(单片)的情形下，在NewSQL的世界中，keyspaces和databases本质上就是一类东西。最后，是时候开始我们的旅程了。 + +切换到helm示例目录: +``` sh +cd examples/helm +``` + +在此目录中，您将看到一组yaml文件。每个文件名的第一个数字表示示例的阶段。接下来的两位数字表示执行它们的顺序。例如'101_initial_cluster.yaml'是第一阶段的第一个文件。我们现在将执行: + +``` sh +helm install ../../helm/vitess -f 101_initial_cluster.yaml +``` + +这将创建一个带有单个keyspace空间的初始Vitess集群。 + + +### 验证集群 + +一旦成功，您应该看到以下状态： + +``` sh +~/...vitess/helm/vitess/templates> kubectl get pods,jobs +NAME READY STATUS RESTARTS AGE +po/etcd-global-2cwwqfkf8d 1/1 Running 0 14m +po/etcd-operator-9db58db94-25crx 1/1 Running 0 15m +po/etcd-zone1-btv8p7pxsg 1/1 Running 0 14m +po/vtctld-55c47c8b6c-5v82t 1/1 Running 1 14m +po/vtgate-zone1-569f7b64b4-zkxgp 1/1 Running 2 14m +po/zone1-commerce-0-rdonly-0 6/6 Running 0 14m +po/zone1-commerce-0-replica-0 6/6 Running 0 14m +po/zone1-commerce-0-replica-1 6/6 Running 0 14m + +NAME DESIRED SUCCESSFUL AGE +jobs/commerce-apply-schema-initial 1 1 14m +jobs/commerce-apply-vschema-initial 1 1 14m +jobs/zone1-commerce-0-init-shard-master 1 1 14m +``` + + +如果已安装MySQL客户端，则现在应该可以使用以下命令连接到群集： + +``` sh +~/...vitess/examples/helm> ./kmysql.sh +mysql> show tables; ++--------------------+ +| Tables_in_commerce | ++--------------------+ +| corder | +| customer | +| product | ++--------------------+ +3 rows in set (0.01 sec) +``` + +您还可以使用以下命令浏览vtctld控制台：（Ubuntu） + +``` sh +./kvtctld.sh +``` + +### Minikube自定义 + +helm示例基于`values.yaml`文件（Vitess的默认的helm chart）。为了在Minikube下运行，已执行以下覆盖： + +* `resources`: +已经被淘汰了。这提示Kubernetes环境使用任何可用的东西。请注意，建议不要将其用于生产环境。在这种情况下，您应该将`helm/vitess/values.yaml`作为基线开始迭代。 + +* etcd和VTGate副本设置为1。在生产环境中，应该有3-5个etcd副本。 VTGate服务器的数量需要根据群集大小进行扩展。 +* `mysqlProtocol.authType`设置为`none`。这应该改为`secret`，证书以Kubernetes的秘钥方式存储。 +* 在生产中不推荐使用`NodePort`的服务类型。您可以选择不将这些endpoints暴露给Kubernetes以外的任何系统。另一种选择是创建Ingress控制器。 + +### 拓扑 + +helm chart指定一个非拆分的keyspace: `commerce`。非拆分的keyspace有一个单独的叫做 +`0`的分片。 + +注意： keyspace/shards是一个集群的全局实体。和cell并无关系。理想情况下，你需要单独列出来keyspace/shards。对于cell来说，你只需要指定哪些keyspace/shards部署在cell之中。为了简单起见，我们可以简单的认为接下来提到的keyspace/shards在不同的cell里。 + +在这次部署中，我们启动两个`replica`角色的tablet和一个`rdonly`角色的tablet。部署后，其中一个`replica`角色的tablet自动被选为master。在vtctld控制台中，你应该看到一个`master`，一个`replica`和一个`rdonly` vttablets。 + +设置replicat角色的tablet的目的是为OLTP提供读流量，rdonly角色的tablet是做分析使用，或者用于执行集群的日常维护工作，如备份、重新分片。rdonly副本容忍和主之间有较大延迟，因为上述维护工作需要暂停主从复制。 + +在我们的用例中，我们为每个分片配置一个rdonly副本以执行重做分片操作。 + +### 表结构 + +``` sql +create table product( + sku varbinary(128), + description varbinary(128), + price bigint, + primary key(sku) +); +create table customer( + customer_id bigint not null auto_increment, + email varbinary(128), + primary key(customer_id) +); +create table corder( + order_id bigint not null auto_increment, + customer_id bigint, + sku varbinary(128), + price bigint, + primary key(order_id) +); +``` + +为简化示例，我们只建少量几张表，每张表少量字段。能够说明流程就好： + +* `product` 表包含所有产品的产品信息。 +* `customer` table有一个具有自动增量的customer_id。典型的customer表将包含更多列，有时还有更多详细信息表。 +* `corder` 表 (这么命名这张表是因为 `order` 是SQL 保留字段) 有一个 order_id 自增列。它同样也是customer(customer_id) 和 product(sku)的外键。 + +### VSchema + +由于Vitess是一个分布式系统，因此通常需要VSchema (Vitess schema)来描述keyspaces的组织方式。 + +``` json +{ + "tables": { + "product": {}, + "customer": {}, + "corder": {} + } +} +``` + +对于但分片的keyspace来说, VSchema非常简单; 它只是展示出keyspace的所有table。 + +注意：在单分片keyspace情况下，VSchema不是严格意义上需要定义的，因为Vitess知道没有其他的keyspaces，所以会将所有的查询流量转发到当前的keyspace上。 + +## Vertical Split + + +由于改革开放的深入，自贸区生意红红火火。单品马黛茶摆上了你网站的货架，尝鲜者蜂拥而至前来购买。 +随着越来越多的用户涌向你的网站和应用程序，`customer`和`corder`表开始以惊人的速度增长。为了跟上进度，您需要将`customer`和`corder` 移动到它们自己的keyspace中来分隔这些表。由于产品数量与马黛茶类型数量一致(不会有太多的马黛茶类型)，因此您无需对产品表进行分片。 + + +让我们在数据表中添加一些数据来说明垂直分割的工作原理. + +``` sh +./kmysql.sh < ../common/insert_commerce_data.sql +``` + +我们可以看看刚插入的内容： + +``` sh +./kmysql.sh --table < ../common/select_commerce_data.sql +Using commerce/0 +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 4 | dan@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +Product ++----------+-------------+-------+ +| sku | description | price | ++----------+-------------+-------+ +| SKU-1001 | Monitor | 100 | +| SKU-1002 | Keyboard | 30 | ++----------+-------------+-------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 4 | 4 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ + +``` + +注意我们在使用 keyspace `commerce/0` 从我们的表中查询数据。 + +### 创建 Keyspace + +对于后续命令，可以方便地捕获发布的名称并保存到变量中： + +``` sh +export release=$(helm ls -q) +``` + +对于垂直拆分，我们首先需要创建一个特殊的`served_from`keyspace。该keyspace作为`commerce`keyspace的别名。发送到此keyspace的任何查询都将重定向到`commerce`。创建后，我们可以将表垂直拆分到新的keyspace，而无需让应用程序感知此更改： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 201_customer_keyspace.yaml +``` + +在查看yaml文件时，在以前的版本中唯一添加的是以下任务： + + +``` yaml +jobs: + - name: "create-customer-ks" + kind: "vtctlclient" + command: "CreateKeyspace -served_from='master:commerce,replica:commerce,rdonly:commerce' customer" +``` +这会在拓扑中创建一个条目，指示必须将对master，replica或rdonly发送给`customer`的任何请求重定向到（来自）`commerce`。这些tablet的指定重定向将用于控制我们如何从`commerce`转换为`customer`。 + +此工作的成功完成应显示为： + +``` sh +NAME DESIRED SUCCESSFUL AGE +jobs/vtctlclient-create-customer-ks 1 1 10s +``` + +### Customer Tablets + +现在，您必须创建vtTablet实例来备份这个新的keyspace，您将在其中移动必要的表： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 202_customer_tablets.yaml +``` + +yaml文件有少量修改： + +``` yaml + - name: "commerce" + shards: + - name: "0" + tablets: + - type: "replica" + vttablet: + replicas: 2 + - type: "rdonly" + vttablet: + replicas: 1 + vschema: + vsplit: |- + { + "tables": { + "product": {} + } + } + - name: "customer" + shards: + - name: "0" + tablets: + - type: "replica" + vttablet: + replicas: 2 + - type: "rdonly" + vttablet: + replicas: 1 + copySchema: + source: "commerce/0" + tables: + - "customer" + - "corder" + vschema: + vsplit: |- + { + "tables": { + "customer": {}, + "corder": {} + } + } +``` + +当然，最显著的变化是为新的keyspace实例化vtablet。此外： + +* 你将customer和corder从commerce的 VSchema中挪至customer的VSchema中。注意物理表仍然在commerce中。 +* 您请求使用`copySchema`指令将customer和corder的架构复制到customer。 + +vschema中的改变没造成任何影响，因为发送给客户的任何查询仍然被重定向到commerce库上，在commerce库中所有的数据仍然存在。 + +完成此步骤后，应该有六个正在运行的vtablet pods，并且必须成功完成以下新作业： + +``` sh +NAME DESIRED SUCCESSFUL AGE +jobs/commerce-apply-vschema-vsplit 1 1 5m +jobs/customer-apply-vschema-vsplit 1 1 5m +jobs/customer-copy-schema-0 1 1 5m +jobs/zone1-customer-0-init-shard-master 1 1 5m +``` + +### 垂直拆分克隆 + +下一步： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 203_vertical_split.yaml +``` +开始将数据从commerce迁移到customer的过程。此文件的新内容是： + +``` yaml +jobs: + - name: "vertical-split" + kind: "vtworker" + cell: "zone1" + command: "VerticalSplitClone -min_healthy_rdonly_tablets=1 -tables=customer,corder customer/0" +``` + +对于大型表，此作业可能会运行很多天，如果失败，则可能会重新启动。此作业执行以下任务： + + +* 从commerce库中的customer表和corder表脏拷贝数据到customer库中的表。 +* 停止在Commerce的RDOnly vttablet上的复制并执行最终同步。 +* 从commerce-> customer启动过滤复制过程，使customer库的表与commerce库中的表保持同步。 + +注意：在生产环境中，你可能希望在开始切换之前多次运行`SplitDiff`作业，对复制执行多次健全性检查： + + +``` yaml +jobs: + - name: "vertical-split-diff" + kind: "vtworker" + cell: "zone1" + command: "VerticalSplitDiff -min_healthy_rdonly_tablets=1 customer/0" +``` + +我们可以通过检查keyspace中的数据来查看VerticalSplitClone的结果。请注意，`customer`和`corder` 表中的所有数据都已复制过来。 + +``` sh +./kmysql.sh --table < ../common/select_customer0_data.sql +Using customer/0 +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 4 | dan@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 4 | 4 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ + +``` + +### 切换 + +一旦您确认customer和corder表正在从commerce库中不断更新，您就可以切断流量。这通常分三步执行：`rdonly`, `replica` 和 `master`: + +切 rdonly 和 replica: + +``` sh +helm upgrade $release ../../helm/vitess/ -f 204_vertical_migrate_replicas.yaml +``` + +切 master: + +``` sh +helm upgrade $release ../../helm/vitess/ -f 205_vertical_migrate_master.yaml +``` + +完成此操作后，`commerce`和`corder`表在`commerce`库中将不能访问。您可以尝试从中进行读取来验证这一点。 + +``` sh +./kmysql.sh --table < ../common/select_commerce_data.sql +Using commerce/0 +Customer +ERROR 1105 (HY000) at line 4: vtgate: http://vtgate-zone1-5ff9c47db6-7rmld:15001/: target: commerce.0.master, used tablet: zone1-1564760600 (zone1-commerce-0-replica-0.vttablet), vttablet: rpc error: code = FailedPrecondition desc = disallowed due to rule: enforce blacklisted tables (CallerID: userData1) +``` + +replica和rdonly可以回切，但，切主是单向的，不可反转。这是垂直拆分的限制。未来不久会解决这个问题。目前，应注意在转换完成后不会发生数据丢失或可用性丢失。 + +### 清理 + +在庆祝您第一次成功的`垂直拆分`之后，您需要清理剩余的组件： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 206_clean_commerce.yaml +``` + +您可以看到commerce库上以下DML语句 + + +``` sql + postsplit: |- + drop table customer; + drop table corder; +``` + +这些表由customer库提供，现在，它们应该从commerce中删除。 + +``` yaml +jobs: + - name: "vclean1" + kind: "vtctlclient" + command: "SetShardTabletControl -blacklisted_tables=customer,corder -remove commerce/0 rdonly" + - name: "vclean2" + kind: "vtctlclient" + command: "SetShardTabletControl -blacklisted_tables=customer,corder -remove commerce/0 replica" + - name: "vclean3" + kind: "vtctlclient" + command: "SetShardTabletControl -blacklisted_tables=customer,corder -remove commerce/0 master" +``` + +这些‘控制’记录在切换期间`MigrateServedFrom`命令添加，以防止commerce表意外接受写入。现在可以删除它们。 + +在此步骤之后，`customer`和`corder`表不再存在于`commerce` 库中。 + +``` sh +./kmysql.sh --table < ../common/select_commerce_data.sql +Using commerce/0 +Customer +ERROR 1105 (HY000) at line 4: vtgate: http://vtgate-zone1-5ff9c47db6-7rmld:15001/: target: commerce.0.master, used tablet: zone1-1564760600 (zone1-commerce-0-replica-0.vttablet), vttablet: rpc error: code = InvalidArgument desc = table customer not found in schema (CallerID: userData1) +``` + +## 水平分片 + +你花重金雇佣的DBA此时已经吓坏了，MYSQL性能在下降，他们想做点儿什么，又不知从何入手，只有不停的微信轰炸你：老板，Keyspace中的数据量已经越来越大了，QPS快抗不住了，咋整？！你微微一笑，小手一挥，别怕，咱有Vitess！咋整，水平拆呀！ +玩笑归玩笑，虽然Vitess为非拆分的单片keyspace提供查询保护和连接池功能，[不懂的看这里看这里](https://vitess.io/blog/2019-06-17-unsharded-vitess-benefits/)，但Vitess真正的价值在于水平分片。 + +### 准备工作 + +在开始重新分片过程之前，您需要做出一些决定并准备系统以进行水平重新分片。重要提示，这是在开始垂直拆分之前应该完成的事情。但是，这是一个很好的你会来解释在这个过程的早期通常会决定什么。 + +#### Sequences + +要解决的第一个问题:customer和corder表都有自增列。然而，分片的情况下并不适用。vitess通过序列提供了一个等价的特性。 + +序列表是一个非拆分单行表，Vitess可以使用它来生成单调递增的id。生成id的语法是： +`select next :n values from customer_seq`。 提供此表的vttablet能够为大量此类ID提供服务，因为值被缓存的，并且服务于内存之外。缓存值是可配置的。 + +vschema允许您将表的列与序列表相关联。完成后，该表上的insert将透明地从sequence表中获取一个ID，填充该值，并将该行路由到适当的shard。此设计向后兼容mysql的`auto_increment`属性的工作方式。 + +由于序列是非拆分表，因此它们将存储在commerce数据库中。架构如下： + + +``` sql +create table customer_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into customer_seq(id, next_id, cache) values(0, 1000, 100); +create table order_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into order_seq(id, next_id, cache) values(0, 1000, 100); +``` + +请注意create table语句中`vitess_sequence`注释。 VTTablet将使用此元数据将此表视为序列。 + +* `id` 总是 0 +* `next_id` 设置为 `1000`: 该值应该比目前使用的`auto_increment`最大值设置的大一些。 +* `cache` :`cache`指定在vttablet在更新`next_id`之前缓存的值的数量。 + +较高的缓存值会获取更高性能。但是，如果通过reparent切换主，那么缓存的值将丢失。新主将从旧主人写入表中的`next_id`值开始计算。 + +VTGate服务器知道谁是序列表。这是通过更新commerce库的VSchema来完成的，如下所示： + +``` json +{ + "tables": { + "customer_seq": { + "type": "sequence" + }, + "order_seq": { + "type": "sequence" + }, + "product": {} + } +} +``` +#### Vindexes + +下一个决定是关于分片键，又称作主Vindex。关于Vindex你可以理解为一个方法，这个方法决定根据什么条件将一行数据放置到不同的分片中。如何选择分片键需要综合考虑才能得出结果，涉及以下考虑因素： + +* 什么是QPS最高的查询，以及它们的where子句是什么？ +* 列的[索引基数](https://blog.csdn.net/tiansidehao/article/details/78931765)，一定要分散 +* 你是否想要对模式建模，以便知道有些行在分片中可以进行join，而不需要跨越分片？ +* 你是否希望同一事务中的某些行能够在一个分片内聚合？ + +综上考虑，在我们的用例中，我们可以确定： + +* 对于customer表，最常见的where子句使用`customer_id`。所以，它应该有一个主Vindex。 +* 鉴于它拥有大量用户，其索引基数也很高。 +* 对于corder表，我们可以选择`customer_id`和`order_id`。鉴于我们的应用程序经常在`customer_id`列上将`customer`与`corder`连接起来，选择`customer_id`作为`corder`表的主Vindex将是有益的。 +* 巧合的是，事务还会更新`corder`表及其对应的`customer`行。这进一步强化了将'customer_id`用作主Vindex的决定。 + +注意：在`corder.order_id`上创建辅助查找Vindex可能是值得的。这不是示例的一部分。我们将在高级部分讨论这个问题。 + +注意：对于某些用例，`customer_id`实际上可能映射到`tenant_id`。在这种情况下，租户ID的基数可能太低。这种系统在其where子句中使用其他高基数列的查询也很常见。在决定采用哪列作为主Vindex时，应考虑这些因素。 + +总而言之，我们为`customer`提供了以下VSchema: + +``` json +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "customer": { + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "customer_id", + "sequence": "customer_seq" + } + }, + "corder": { + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "order_id", + "sequence": "order_seq" + } + } + } +} +``` + +请注意，我们现在已将keyspace标记为分片。这种改变同样会改变Vitess处理这个keyspace的方式。以前工作的一些复杂查询可能不再起作用。这是进行全面测试以确保所有查询都有效的好时机。如果任何查询失败，您可以暂时将keyspace恢复为未分片(单片)。 + +由于主vindex列是`BIGINT`，我们选择`hash`作为主vindex，这是一种将行分配到各种分片的伪随机方式。 + +注意：对于`VARCHAR`列，请使用`unicode_loose_md5`。对于`VARBINARY`，使用`binary_md5`。 + +注意：Vitess中的所有vindex都是插件。如果预定义的vindexs都不符合您的需求，您可以开发自己的自定义vindex。 + +既然我们做出了所有重要的决定，那么就应该应用这些变化： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 301_customer_sharded.yaml +``` + +要注意的工作： + +``` sh +NAME DESIRED SUCCESSFUL AGE +jobs/commerce-apply-schema-seq 1 1 19s +jobs/commerce-apply-vschema-seq 1 1 19s +jobs/customer-apply-schema-sharded 1 1 19s +jobs/customer-apply-vschema-sharded 1 1 19s +``` + +### 创建新分片 + +此时，您已完成分片VSchema并且检查了您业务的所有SQL以确保它们在多分片上仍然有效。现在，是时候开始水平拆分了。 + +水平分片过程的工作原理是将现有分片拆分为较小的分片。这种类型的重新分片最适合Vitess。在某些用例中，您可能希望启动新分片并在最近创建的分片中添加新行。Vitess也可以做到这一点，假设按数值进行分割（office_id）。将会有一个新的办公室编号205.目前，分片定义会将其插入到碎片4中，但尚未插入205的值。所以我们改变定义，说数字>=205要去一个新的分片，然后我们开始插入。这样，office_id大于205的就会去到我们新的分片中，只要我们提前设定好vindex方法。 + + +我们必须创建新的目标分片： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 302_new_shards.yaml +``` + +我们正在应用的变化是： + +``` yaml + - name: "customer" + shards: + - name: "0" + tablets: + - type: "replica" + vttablet: + replicas: 2 + - type: "rdonly" + vttablet: + replicas: 1 + - name: "-80" + tablets: + - type: "replica" + vttablet: + replicas: 2 + - type: "rdonly" + vttablet: + replicas: 1 + copySchema: + source: "customer/0" + - name: "80-" + tablets: + - type: "replica" + vttablet: + replicas: 2 + - type: "rdonly" + vttablet: + replicas: 1 + copySchema: + source: "customer/0" +``` + +Shard 0已经存在了。我们现在添加了分片`-80`和`80 -`。我们还添加了`copySchema`指令，该指令请求将分片0中的模式复制到新的分片中。 + + +#### 分片命名 + + `-80` 和 `80-`是什么玩意儿? 分片名字具有下列特征: + +* 表示一个范围，包括左边界，右边界不包括在内。 +* 十六进制 +* 左对齐 +* 左`-` 前缀表示: 任何小于右值的值 +* 右`-` 前缀: 任何大于或等于左值的值 +* 普通的 `-` 表示全部范围 + +这是什么意思: `-80` == `00-80` == `0000-8000` == `000000-800000` + +`80-` 和 `80-FF` 是不一样的。 这是因为： + +`80-FF` == `8000-FF00`. 因此 `FFFF` 会超出 `80-FF` 范围. + +`80-` 意味着: 大于或等于`0x80`的任何值。 + +`hash` vindex产生一个8字节的数。这意味着所有小于“0x8000000000000000”的数字都将落在分片`-80`中。任何具有最高位集的> =`0x8000000000000000`的数字，属于shard`80-`。 + +这种左对齐的方法允许您拥有任意长度的keyspace ID。但是，最重要的位是左边的位。 + +例如，“md5”哈希产生16个字节。也可以用作keyspace的ID。 + +任意长度的`varbinary`也可以按原样映射到keyspace id。这就是`binary`vindex所做的。 + +在上面的例子中，我们创建了两个shard：任何没有其最左边位集的keyspace id都将转到`-80`。其他人都会去“80-”。 + +应用上述更改将导致创建另外六个vttablet pod，以及以下新作业： + +``` sh +NAME DESIRED SUCCESSFUL AGE +jobs/customer-copy-schema-80-x 1 1 58m +jobs/customer-copy-schema-x-80 1 1 58m +jobs/zone1-customer-80-x-init-shard-master 1 1 58m +jobs/zone1-customer-x-80-init-shard-master 1 1 58m +``` +此时，表已在新分片中创建但尚未有数据。 + +``` sh +./kmysql.sh --table < ../common/select_customer-80_data.sql +Using customer/-80 +Customer +COrder +./kmysql.sh --table < ../common/select_customer80-_data.sql +Using customer/80- +Customer +COrder +``` + +### SplitClone + +SplitClone的过程类似于VerticalSplitClone。它启动水平重新分割过程： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 303_horizontal_split.yaml +``` + +这开始了以下工作： + +``` yaml +jobs: + - name: "horizontal-split" + kind: "vtworker" + cell: "zone1" + command: "SplitClone -min_healthy_rdonly_tablets=1 customer/0" +``` + +对于大表，此作业可能会运行很多天，如果失败可以重新启动。此作业执行以下任务： + +* 将customer/0的数据脏拷贝到两个新分片中。但行是根据目标分片拆分的。 +* 停止在customer/0 rdonly tablet上复制并执行最终同步。 +* 根据行所属的分片，向其中一个或另一个分片发送更改，从而启动从customer/0到两个碎片的过滤复制过程。开启过滤复制，Vitess会根据某行数据的路由字段数值根据路由算法计算出一个数值，如果此数值<-80,此行将落到第一个分片，如果此数值>-80，那么此行将去到另一个分片。 + + +一旦 `SplitClone` 完成， 你会看到如下信息: + +``` sh +NAME DESIRED SUCCESSFUL AGE +jobs/vtworker-horizontal-split 1 1 5m +``` + +与`VerticalSplitDiff`对应的操作是 `SplitDiff`。它可用于验证重新分片过程的数据完整性。 + + +``` yaml +jobs: + - name: "horizontal-split-diff" + kind: "vtworker" + cell: "zone1" + command: "SplitDiff -min_healthy_rdonly_tablets=1 customer/-80" +``` + +请注意，SplitDiff的最后一个参数是目标分片。您需要为每个目标分片运行一个作业。此外，您无法并行运行它们，因为它们需要`rdonly`实例从集群中摘掉（停止主从复制）才能执行比较。 + +注意：此示例实际上不运行此命令。 + +注意：SplitDiff可用于分割分片以及合并分片。 + +### 切换 +现在您已验证表中数据是从源分片持续更新的，您可以切换流量。这通常分三步执行：`rdonly`，`replica`和`master`： + +切rdonly 和 replica: + +``` sh +helm upgrade $release ../../helm/vitess/ -f 304_migrate_replicas.yaml +``` + +切master: + +``` sh +helm upgrade $release ../../helm/vitess/ -f 305_migrate_master.yaml +``` + +在*master*迁移期间，原始分片主先停写。接下来，程序将等待新的分片主追平过滤复制，然后再允许它们开始服务。由于源分片的replica mysql上的binlog被实时过滤复制消费到不同分片上，因此切主时的延迟应该不会太高，因此只会有几秒钟的主不可用性。 + +replica和rdonly切换可以自由逆转。与垂直拆分不同，水平拆分也是可逆的。您只需在切主时添加一个`-reverse_replication`标志即可。你可以理解成建立反方向的过滤复制，如果带着这个标志，你发现用新片有问题的时候，你就可以随时切换回去，因为反向的过滤复制保证新旧分片上的数据是完全一致的。 + +现在应该可以看到复制到新分片上的数据了。 + +``` sh +./kmysql.sh --table < ../common/select_customer-80_data.sql +Using customer/-80 +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ + +./kmysql.sh --table < ../common/select_customer80-_data.sql +Using customer/80- +Customer ++-------------+----------------+ +| customer_id | email | ++-------------+----------------+ +| 4 | dan@domain.com | ++-------------+----------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 4 | 4 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ +``` + +### 清理 + +在庆祝第二次成功水平拆分之后，您现在准备清理剩余的组件： + + +``` sh +helm upgrade $release ../../helm/vitess/ -f 306_down_shard_0.yaml +``` + +在这个yaml中，我们只删除了分片0.这将导致所有这些vttablet pod被删除。但是分片元数据仍然存在。我们可以用这个命令清理它（在所有的vttablet进程退出之后）： + + +``` sh +helm upgrade $release ../../helm/vitess/ -f 307_delete_shard_0.yaml +``` + +此命令运行以下作业： + +``` yaml +jobs: + - name: "delete-shard0" + kind: "vtctlclient" + command: "DeleteShard -recursive customer/0" +``` + +除此之外，您还需要手动删除与此分片相关联PVC。PVC是k8s里的存储概念，[概念看这里](https://www.cnblogs.com/styshoo/p/6731425.html) + +而且，作为最后的操作，我们删除最后执行的工作： + +``` sh +helm upgrade $release ../../helm/vitess/ -f 308_final.yaml +``` + +### 拆除 (可选) + +如果您不继续进行其他练习，则可以删除整个示例。 + +``` sh +helm delete $release +``` + +您还需要删除PVC + +``` sh +kubectl delete pvc $(kubectl get pvc | grep vtdataroot-zone1 | awk '{print $1}') +``` + +恭喜你完成这个练习！ diff --git a/content/zh/docs/19.0/get-started/local.md b/content/zh/docs/19.0/get-started/local.md new file mode 100644 index 000000000..ae9d1c053 --- /dev/null +++ b/content/zh/docs/19.0/get-started/local.md @@ -0,0 +1,653 @@ +--- +title: 本机运行Vitess +description: 如何本机构建和测试Vitess +weight: 4 +featured: true +--- + +本指南涵盖了从预编译的二进制本地文件安装文件，进行本地测试。我们启3个mysqld。建议使用大于4GB的RAM，以及20GB的可用磁盘空间。 + +## 安装包 + +PlanetScale 提供 [每周构建](https://github.com/planetscale/vitess-releases/releases) 适用于64位Linux的Vitess。 + +1. 从 GitHub 上下载解压 [最近发布的`.tar.gz`](https://github.com/planetscale/vitess-releases/releases) 。 +2. 安装 MySQL: +```bash +# Apt based +sudo apt-get install mysql-server +# Yum based +sudo yum install mysql-server +``` + +_Vitess支持MySQL 5.6+和MariaDB 10.0+。我们建议使用MySQL 5.7。_ + +## 禁用 AppArmor + +我们建议您卸载或禁用Apparmor。有些版本的MySQL提供了Vitess工具尚未识别的默认Apparmor配置。当vitess通过mysqlctl工具初始化mysql实例时，这会导致各种权限失败。这只是测试环境中的一个问题。如果生产中需要apparmor，则可以适当配置mysql实例，而不必使用`mysqlctl`： + +```bash +sudo service apparmor stop +sudo service apparmor teardown # safe to ignore if this errors +sudo update-rc.d -f apparmor remove +``` + +重新启动以确保完全禁用Apparmor。 + +## 配置环境 + +将以下内容添加到您的`.bashrc`文件中。确保将`/path/to/extracted-tarball`替换为解压最新版本文件的实际路径： + +```bash +export VTROOT=/path/to/extracted-tarball +export VTTOP=$VTROOT +export MYSQL_FLAVOR=MySQL56 +export VTDATAROOT=${HOME}/vtdataroot +export PATH=${VTROOT}/bin:${PATH} +``` + +准备好开始您的第一个集群了吗？let's go ! + +## 启动单个 Keyspace 集群 + +首先将 Vitess 中包含的本地示例复制到你喜欢的位置。对于第一个例子，我们将部署一个[单个不分片 keyspace](../../concepts/keyspace). 文件 `101_initial_cluster.sh` 是第`1`阶段的第`01`个例子。让我们现在执行它: + +```sh +cp -r /usr/local/vitess/examples/local ~/my-vitess-example +cd ~/my-vitess-example +./101_initial_cluster.sh +``` + +您应该看到类似于以下内容的输出： + +```bash +~/...vitess/examples/local> ./101_initial_cluster.sh +enter zk2 env +Starting zk servers... +Waiting for zk servers to be ready... +Started zk servers. +Configured zk servers. +enter zk2 env +Starting vtctld... +Access vtctld web UI at http://ryzen:15000 +Send commands with: vtctlclient -server ryzen:15999 ... +enter zk2 env +Starting MySQL for tablet zone1-0000000100... +Starting MySQL for tablet zone1-0000000101... +Starting MySQL for tablet zone1-0000000102... +``` +您还可以使用`pgrep`验证进程是否已启动： + +``` sh +~/...vitess/examples/local> pgrep -fl vtdataroot +5451 zksrv.sh +5452 zksrv.sh +5453 zksrv.sh +5463 java +5464 java +5465 java +5627 vtctld +5762 mysqld_safe +5767 mysqld_safe +5799 mysqld_safe +10162 mysqld +10164 mysqld +10190 mysqld +10281 vttablet +10282 vttablet +10283 vttablet +10447 vtgate +``` + +如果您遇到任何错误，例如已在使用的端口，您可以终止进程并重新开始： + +```bash +pkill -f '(vtdataroot|VTDATAROOT)' # kill Vitess processes +``` + +## 连接集群 + +您现在应该可以使用以下命令连接到集群： + +``` sh +~/...vitess/examples/local> mysql -h 127.0.0.1 -P 15306 +Welcome to the MySQL monitor. Commands end with ; or \g. +mysql> show tables; ++-----------------------+ +| Tables_in_vt_commerce | ++-----------------------+ +| corder | +| customer | +| product | ++-----------------------+ +3 rows in set (0.01 sec) +``` + +您还可以使用以下URL浏览到vtctld控制台： + +``` sh +http://localhost:15000 +``` + +### 拓扑 + +在这个例子中，我们使用单片keyspace：`commerce`。单分片的keysoace有一个名为`0`的分片。 + +注意：keyspace/shards是集群的全局实体， +keyspaces/shard对于单元来说是一个独立的概念——所以理想情况下，它们应该与cell分开显示。例如：您应该先创建keyspace，然后再决定将它们部署到何处。 + +在此次部署中，我们启动两个`replica`类型表和一个`rdonly`类型的tablet。部署后，其中一个`replica` tablet 类型将自动被选为主服务器。在vtctld控制台中，你应该看到一个`master`，一个`replica`和一个`rdonly` vttablets。 + +设置replicat角色的tablet的目的是为OLTP提供读流量，rdonly角色的tablet是做分析使用，或者用于执行集群的日常维护工作，如备份、重新分片。rdonly副本容忍和主之间有较大延迟，因为上述维护工作需要暂停主从复制。 + +在我们的用例中，我们为每个shard提供一个rdonly副本，以便执行resharding(重新分片)操作。 + +### Schema + +``` sql +create table product( + sku varbinary(128), + description varbinary(128), + price bigint, + primary key(sku) +); +create table customer( + customer_id bigint not null auto_increment, + email varbinary(128), + primary key(customer_id) +); +create table corder( + order_id bigint not null auto_increment, + customer_id bigint, + sku varbinary(128), + price bigint, + primary key(order_id) +); +``` + +为简化示例，我们只建少量几张表，每张表少量字段。能够说明流程就好： + +* `product` 表包含所有产品的产品信息。 +* `customer` table有一个具有自动增量的customer_id。典型的customer表将包含更多列，有时还有更多详细信息表。 +* `corder` 表 (这么命名这张表是因为 `order` 是SQL 保留字段) 有一个 order_id 自增列。它同样也是customer(customer_id) 和 product(sku)的外键。 + +### VSchema + +由于Vitess是一个分布式系统，因此通常需要VSchema (Vitess schema)来描述keyspaces的组织方式。 + +``` json +{ + "tables": { + "product": {}, + "customer": {}, + "corder": {} + } +} +``` +对于但分片的keyspace来说, VSchema非常简单; 它只是展示出keyspace的所有table。 + +注意：在单分片keyspace情况下，VSchema不是严格意义上需要定义的，因为Vitess知道没有其他的keyspaces，所以会将所有的查询流量转发到当前的keyspace上。 + +## 垂直拆分 + +由于改革开放的深入，自贸区生意红红火火。单品马黛茶摆上了你网站的货架，尝鲜者蜂拥而至前来购买。 +随着越来越多的用户涌向你的网站和应用程序，`customer`和`corder`表开始以惊人的速度增长。为了跟上进度，您需要将`customer`和`corder` 移动到它们自己的keyspace中来分隔这些表。由于产品数量与马黛茶类型数量一致(不会有太多的马黛茶类型)，因此您无需对产品表进行分片。 + + +让我们在数据表中添加一些数据来说明垂直分割的工作原理. + +``` sql +mysql -h 127.0.0.1 -P 15306 < ../common/insert_commerce_data.sql +``` + +我们可以看看刚插入的内容： + +``` sh +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_commerce_data.sql +Using commerce/0 +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 4 | dan@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +Product ++----------+-------------+-------+ +| sku | description | price | ++----------+-------------+-------+ +| SKU-1001 | Monitor | 100 | +| SKU-1002 | Keyboard | 30 | ++----------+-------------+-------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 4 | 4 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ +``` + +注意我们在使用 keyspace `commerce/0` 从我们的表中查询数据。 + +### Create Keyspace + +对于垂直拆分，我们首先需要创建一个特殊的`served_from`keyspace。该keyspace作为`commerce`keyspace的别名。发送到此keyspace的任何查询都将重定向到`commerce`。创建后，我们可以将表垂直拆分到新的keyspace，而无需让应用程序感知此更改： + +``` sh +./201_customer_keyspace.sh +``` + +This creates an entry into the topology indicating that any requests to master, replica, or rdonly sent to `customer` must be redirected to (served from) `commerce`. These tablet type specific redirects will be used to control how we transition the cutover from `commerce` to `customer`. +这会在拓扑中创建一个条目，指示必须将对master，replica或rdonly发送给`customer`的任何请求重定向到（来自）`commerce`。这些tablet的指定重定向将用于控制我们如何从`commerce`转换为`customer`。 + +### Customer Tablets + +现在，您必须创建vtTablet实例来备份这个新的keyspace，您将在其中移动必要的表： + +``` sh +./202_customer_tablets.sh +``` +当然，最显著的变化是为新的keyspace实例化vtablet。此外： + +* 你将customer和corder从commerce的 VSchema中挪至customer的VSchema中。注意物理表仍然在commerce中。 +* 您请求使用`copySchema`指令将customer和corder的架构复制到customer。 + +vschema中的改变没造成任何影响，因为发送给客户的任何查询仍然被重定向到commerce库上，在commerce库中所有的数据仍然存在。 + +### 垂直拆分克隆 + +下一步： + +``` sh +./203_vertical_split.sh +``` + +开始将数据从commerce迁移到customer的过程。 + +对于大型表，此作业可能会运行很多天，如果失败，则可能会重新启动。此作业执行以下任务： + +* 从commerce库中的customer表和corder表脏拷贝数据到customer库中的表。 +* 停止在Commerce的RDOnly vttablet上的复制并执行最终同步。 +* 从commerce-> customer启动过滤复制过程，使customer库的表与commerce库中的表保持同步。 + +注意：在生产环境中，你可能希望在开始切换之前多次运行`SplitDiff`作业，对复制执行多次健全性检查： + +我们可以通过检查customer keyspace中的数据来查看VerticalSplitClone的结果。请注意，`customer`和`corder`表中的所有数据都已复制过来。 + +``` sh +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_customer0_data.sql +Using customer/0 +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 4 | dan@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 4 | 4 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ + +``` + +### 切换 + +一旦您确认customer和corder表正在从commerce库中不断更新，您就可以切断流量。这通常分三步执行：`rdonly`, `replica` 和 `master`: + +切 rdonly 和 replica: + +``` sh +./204_vertical_migrate_replicas.sh +``` + +切 master: + +``` sh +./205_vertical_migrate_master.sh +``` + +完成此操作后，`commerce`和`corder`表在`commerce`库中将不能访问。您可以尝试从中进行读取来验证这一点。 + +``` sql +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_commerce_data.sql +Using commerce/0 +Customer +ERROR 1105 (HY000) at line 4: vtgate: http://vtgate-zone1-5ff9c47db6-7rmld:15001/: target: commerce.0.master, used tablet: zone1-1564760600 (zone1-commerce-0-replica-0.vttablet), vttablet: rpc error: code = FailedPrecondition desc = disallowed due to rule: enforce blacklisted tables (CallerID: userData1) +``` + +replica和rdonly可以回切，但，切主是单向的，不可反转。这是垂直拆分的限制。未来不久会解决这个问题。目前，应注意在转换完成后不会发生数据丢失或可用性丢失。 + +### 清理 + +在庆祝您第一次成功的`垂直拆分`之后，您需要清理剩余的组件： + +``` sh +./206_clean_commerce.sh +``` + +这些表由customer库提供，现在，它们应该从commerce中删除。 + +这些‘控制’记录在切换期间`MigrateServedFrom`命令添加，以防止commerce表意外接受写入。现在可以删除它们。 + +在此步骤之后，`customer`和`corder`表不再存在于`commerce` 库中。 + +``` sql +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_commerce_data.sql +Using commerce/0 +Customer +ERROR 1105 (HY000) at line 4: vtgate: http://vtgate-zone1-5ff9c47db6-7rmld:15001/: target: commerce.0.master, used tablet: zone1-1564760600 (zone1-commerce-0-replica-0.vttablet), vttablet: rpc error: code = InvalidArgument desc = table customer not found in schema (CallerID: userData1) +``` + +## 水平拆分 + +你花重金雇佣的DBA此时已经吓坏了，MYSQL性能在下降，他们想做点儿什么，又不知从何入手，只有不停的微信轰炸你：老板，Keyspace中的数据量已经越来越大了，QPS快抗不住了，咋整？！你微微一笑，小手一挥，别怕，咱有Vitess！咋整，水平拆呀！ +玩笑归玩笑，虽然Vitess为非拆分的单片keyspace提供查询保护和连接池功能，[不懂的看这里看这里](https://vitess.io/blog/2019-06-17-unsharded-vitess-benefits/)，但Vitess真正的价值在于水平分片。 + +### 准备工作 + +在开始重新分片过程之前，您需要做出一些决定并准备系统以进行水平重新分片。重要提示，这是在开始垂直拆分之前应该完成的事情。但是，这是一个很好的你会来解释在这个过程的早期通常会决定什么。 + +#### 序列表 + +要解决的第一个问题:customer和corder表都有自增列。然而，分片的情况下并不适用。vitess通过序列提供了一个等价的特性。 + +序列表是一个非拆分单行表，Vitess可以使用它来生成单调递增的id。生成id的语法是： +`select next :n values from customer_seq`。 提供此表的vttablet能够为大量此类ID提供服务，因为值被缓存的，并且服务于内存之外。缓存值是可配置的。 + +vschema允许您将表的列与序列表相关联。完成后，该表上的insert将透明地从sequence表中获取一个ID，填充该值，并将该行路由到适当的shard。此设计向后兼容mysql的`auto_increment`属性的工作方式。 + +由于序列是非拆分表，因此它们将存储在commerce数据库中。架构如下： + +``` sql +create table customer_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into customer_seq(id, next_id, cache) values(0, 1000, 100); +create table order_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into order_seq(id, next_id, cache) values(0, 1000, 100); +``` + +请注意create table语句中`vitess_sequence`注释。 VTTablet将使用此元数据将此表视为序列。 + +* `id` 总是 0 +* `next_id` 设置为 `1000`: 该值应该比目前使用的`auto_increment`最大值设置的大一些。 +* `cache` :`cache`指定在vttablet在更新`next_id`之前缓存的值的数量。 + +较高的缓存值会获取更高性能。但是，如果通过reparent切换主，那么缓存的值将丢失。新主将从旧主人写入表中的`next_id`值开始计算。 + +VTGate服务器知道谁是序列表。这是通过更新commerce库的VSchema来完成的，如下所示： + +``` json +{ + "tables": { + "customer_seq": { + "type": "sequence" + }, + "order_seq": { + "type": "sequence" + }, + "product": {} + } +} +``` + +#### Vindexes + +下一个决定是关于分片键，又称作主Vindex。关于Vindex你可以理解为一个方法，这个方法决定根据什么条件将一行数据放置到不同的分片中。如何选择分片键需要综合考虑才能得出结果，涉及以下考虑因素： + +* 什么是QPS最高的查询，以及它们的where子句是什么？ +* 列的[索引基数](https://blog.csdn.net/tiansidehao/article/details/78931765)，一定要分散 +* 你是否想要对模式建模，以便知道有些行在分片中可以进行join，而不需要跨越分片？ +* 你是否希望同一事务中的某些行能够在一个分片内聚合？ + +综上考虑，在我们的用例中，我们可以确定： + +* 对于customer表，最常见的where子句使用`customer_id`。所以，它应该有一个主Vindex。 +* 鉴于它拥有大量用户，其索引基数也很高。 +* 对于corder表，我们可以选择`customer_id`和`order_id`。鉴于我们的应用程序经常在`customer_id`列上将`customer`与`corder`连接起来，选择`customer_id`作为`corder`表的主Vindex将是有益的。 +* 巧合的是，事务还会更新`corder`表及其对应的`customer`行。这进一步强化了将'customer_id`用作主Vindex的决定。 + +注意：在`corder.order_id`上创建辅助查找Vindex可能是值得的。这不是示例的一部分。我们将在高级部分讨论这个问题。 + +注意：对于某些用例，`customer_id`实际上可能映射到`tenant_id`。在这种情况下，租户ID的基数可能太低。这种系统在其where子句中使用其他高基数列的查询也很常见。在决定采用哪列作为主Vindex时，应考虑这些因素。 + +总而言之，我们为`customer`提供了以下VSchema: + +``` json +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "customer": { + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "customer_id", + "sequence": "customer_seq" + } + }, + "corder": { + "column_vindexes": [ + { + "column": "customer_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "order_id", + "sequence": "order_seq" + } + } + } +} +``` + +请注意，我们现在已将keyspace标记为分片。这种改变同样会改变Vitess处理这个keyspace的方式。以前工作的一些复杂查询可能不再起作用。这是进行全面测试以确保所有查询都有效的好时机。如果任何查询失败，您可以暂时将keyspace恢复为未分片(单片)。 + +由于主vindex列是`BIGINT`，我们选择`hash`作为主vindex，这是一种将行分配到各种分片的伪随机方式。 + +注意：对于`VARCHAR`列，请使用`unicode_loose_md5`。对于`VARBINARY`，使用`binary_md5`。 + +注意：Vitess中的所有vindex都是插件。如果预定义的vindexs都不符合您的需求，您可以开发自己的自定义vindex。 + +既然我们做出了所有重要的决定，那么就应该应用这些变化： + +``` sh +./301_customer_sharded.sh +``` + +### Create new shards + +此时，您已完成分片VSchema并且检查了您业务的所有SQL以确保它们在多分片上仍然有效。现在，是时候开始水平拆分了。 + +水平分片过程的工作原理是将现有分片拆分为较小的分片。这种类型的重新分片最适合Vitess。在某些用例中，您可能希望启动新分片并在最近创建的分片中添加新行。Vitess也可以做到这一点，假设按数值进行分割（office_id）。将会有一个新的办公室编号205.目前，分片定义会将其插入到碎片4中，但尚未插入205的值。所以我们改变定义，说数字>=205要去一个新的分片，然后我们开始插入。这样，office_id大于205的就会去到我们新的分片中，只要我们提前设定好vindex方法。 + +我们必须创建新的目标分片： + +``` sh +./302_new_shards.sh +``` +Shard 0已经存在了。我们现在添加了分片`-80`和`80 -`。我们还添加了`copySchema`指令，该指令请求将分片0中的模式复制到新的分片中。 + +#### 分片命名 + +`-80` 和 `80-`是什么玩意儿? 分片名字具有下列特征: + +* 表示一个范围，包括左边界，右边界不包括在内。 +* 十六进制 +* 左对齐 +* 左`-` 前缀表示: 任何小于右值的值 +* 右`-` 前缀: 任何大于或等于左值的值 +* 普通的 `-` 表示全部范围 + +这是什么意思: `-80` == `00-80` == `0000-8000` == `000000-800000` + +`80-` 和 `80-FF` 是不一样的。 这是因为： + +`80-FF` == `8000-FF00`. 因此 `FFFF` 会超出 `80-FF` 范围. + +`80-` 意味着: 大于或等于`0x80`的任何值。 + +`hash` vindex产生一个8字节的数。这意味着所有小于“0x8000000000000000”的数字都将落在分片`-80`中。任何具有最高位集的> =`0x8000000000000000`的数字，属于shard`80-`。 + +这种左对齐的方法允许您拥有任意长度的keyspace ID。但是，最重要的位是左边的位。 + +例如，“md5”哈希产生16个字节。也可以用作keyspace的ID。 + +任意长度的`varbinary`也可以按原样映射到keyspace id。这就是`binary`vindex所做的。 + +在上面的例子中，我们创建了两个shard：任何没有其最左边位集的keyspace id都将转到`-80`。其他人都会去“80-”。 + +应用上述更改将导致创建另外六个vttablet实例。 + +此时，表已在新分片中创建但尚未包含数据。 + +``` sql +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_customer-80_data.sql +Using customer/-80 +Customer +COrder +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_customer80-_data.sql +Using customer/80- +Customer +COrder +``` + +### SplitClone + +SplitClone的过程类似于VerticalSplitClone。它启动水平重新分割过程： + +``` sh +./303_horizontal_split.sh +``` + +这开始了以下工作： + "SplitClone -min_healthy_rdonly_tablets=1 customer/0": + +对于大表，此作业可能会运行很多天，如果失败可以重新启动。此作业执行以下任务： + +* 将customer/0的数据脏拷贝到两个新分片中。但行是根据目标分片拆分的。 +* 停止在customer/0 rdonly tablet上复制并执行最终同步。 +* 根据行所属的分片，向其中一个或另一个分片发送更改，从而启动从customer/0到两个碎片的过滤复制过程。开启过滤复制，Vitess会根据某行数据的路由字段数值根据路由算法计算出一个数值，如果此数值<-80,此行将落到第一个分片，如果此数值>-80，那么此行将去到另一个分片。 + + +一旦 `SplitClone` 完成， 你会看到如下信息: + + +与`VerticalSplitDiff`对应的操作是 `SplitDiff`。它可用于验证重新分片过程的数据完整性。 + +注意：此示例实际上不运行此命令。 + +请注意，SplitDiff的最后一个参数是目标分片。您需要为每个目标分片运行一个作业。此外，您无法并行运行它们，因为它们需要`rdonly`实例从集群中摘掉（停止主从复制）才能执行比较。 + +注意：SplitDiff可用于分割分片以及合并分片。 + +### 切换 + +现在您已验证表中数据是从源分片持续更新的，您可以切换流量。这通常分三步执行：`rdonly`，`replica`和`master`： + +切 rdonly 和 replica: + +``` sh +./304_migrate_replicas.sh +``` + +切 master: + +``` sh +./305_migrate_master.sh +``` + +在*master*迁移期间，原始分片主先停写。接下来，程序将等待新的分片主追平过滤复制，然后再允许它们开始服务。由于源分片的replica mysql上的binlog被实时过滤复制消费到不同分片上，因此切主时的延迟应该不会太高，因此只会有几秒钟的主不可用性。 + +replica和rdonly切换可以自由逆转。与垂直拆分不同，水平拆分也是可逆的。您只需在切主时添加一个`-reverse_replication`标志即可。你可以理解成建立反方向的过滤复制，如果带着这个标志，你发现用新片有问题的时候，你就可以随时切换回去，因为反向的过滤复制保证新旧分片上的数据是完全一致的。 + +现在应该可以看到复制到新分片上的数据了。 + +``` sh +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_customer-80_data.sql +Using customer/-80 +Customer ++-------------+--------------------+ +| customer_id | email | ++-------------+--------------------+ +| 1 | alice@domain.com | +| 2 | bob@domain.com | +| 3 | charlie@domain.com | +| 5 | eve@domain.com | ++-------------+--------------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 1 | 1 | SKU-1001 | 100 | +| 2 | 2 | SKU-1002 | 30 | +| 3 | 3 | SKU-1002 | 30 | +| 5 | 5 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ + +mysql -h 127.0.0.1 -P 15306 --table < ../common/select_customer80-_data.sql +Using customer/80- +Customer ++-------------+----------------+ +| customer_id | email | ++-------------+----------------+ +| 4 | dan@domain.com | ++-------------+----------------+ +COrder ++----------+-------------+----------+-------+ +| order_id | customer_id | sku | price | ++----------+-------------+----------+-------+ +| 4 | 4 | SKU-1002 | 30 | ++----------+-------------+----------+-------+ +``` + +### 清理 + +在庆祝第二次成功水平拆分之后，您现在准备清理剩余的组件： + +``` sh +./306_down_shard_0.sh +``` + +在这个脚本中，我们刚停止了分片0中的所有的tablet实例。这将导致所有那些vttablet和`mysqld`进程停止。但是分片元数据仍然存在。我们可以用这个命令清理它（在所有的vttablet进程退出之后）： + + +``` sh +./307_delete_shard_0.sh +``` +此脚本运行如下命令： +"`DeleteShard -recursive customer/0`". + +除此之外，您还需要手动删除与此分片关联的磁盘。 + +### 拆除 (可选) + +如果您不继续进行其他练习，则可以删除整个示例。 + +``` sh +./401_teardown.sh +``` diff --git a/content/zh/docs/19.0/get-started/vagrant.md b/content/zh/docs/19.0/get-started/vagrant.md new file mode 100644 index 000000000..9c2f8e6b6 --- /dev/null +++ b/content/zh/docs/19.0/get-started/vagrant.md @@ -0,0 +1,152 @@ +--- +title: 用Vagrant跑Vitess +description: 使用Vagrant在机器上构建Vitess以进行测试和开发的说明 +weight: 4 +featured: true +--- + +[Vagrant](https://www.vagrantup.com/) 是一个在单个工作流程中构建和管理虚拟机环境的工具。通过易于使用的工作流程并专注于自动化，Vagrant降低了开发环境的设置时间，提高了生产力，并使“在我的机器上工作”成为历史。 + +下面的指南将向您展示如何使用此工具在本地环境中构建和运行vitess。 + +{{< info >}} +如果您遇到问题或有疑问，我们建议您在[Slack channel](https://vitess.slack.com)中发布，单击右上角的Slack图标加入。这是一个非常活跃的社区论坛，也是与其他用户互动的好地方 +{{< /info >}} + +## Install dependencies + +1. 在OS上安装 [Vagrant](https://www.vagrantup.com/downloads.html) +1. 安装 [Virtual Box](https://www.virtualbox.org/) + + +## 编译 Vitess {#build-vitess-vagrant} + +1. 将vitess repo克隆到本地环境中： + + ```sh + git clone https://github.com/vitessio/vitess.git + ``` + +2. 从repo目录运行以下命令： + + ```sh + vagrant up + ``` + + 这将使用所有Vitess依赖项来引导VM。 + +3. 完成引导程序后，运行以下命令： + + ```sh + vagrant ssh + ``` + + 第一次连接到VM时，它会自动为您构建vitess。 + +4. 展望未来，如果您想构建项目，您只需要运行： + ```sh + make build + ``` + +## Run Tests + +{{< info >}} +如果您正在使用etcd，请设置以下环境变量： + +```sh +export VT_TEST_FLAGS='--topo-server-flavor=etcd2' +``` + +如果您使用的是Consul，请设置以下环境变量： + +```sh +export VT_TEST_FLAGS='--topo-server-flavor=consul' +``` +{{< /info >}} + +运行`make test`时的默认目标包含一整套测试，旨在帮助Vitess开发人员验证代码更改是否有错。这些测试通过在本地计算机上启动许多服务器来模拟小型Vitess集群。为顺利测试，它们需要大量的资源;建议至少使用8GB RAM和SSD来运行测试。 + +如果您只想检查Vitess是否在您的环境中正常工作，您可以运行一组更轻松的测试： + +```sh +make site_test +``` + +## Start a Vitess cluster + +After completing the instructions above to [build Vitess](#build-vitess-vagrant), you can use the example scripts in the GitHub repo to bring up a Vitess cluster on your local machine. These scripts use `etcd2` as the default [topology service](../../concepts/topology-service) plugin. + +按照指导完成上述[build Vitess](#build-vitess-vagrant)的操作步骤之后，您可以使用GitHub存储库中的示例脚本在本地计算机上开启Vitess集群。这些脚本使用`etcd2`作为默认的[拓扑服务](../../concepts/topology-service)插件。 + + +1. **启动集群** + + ```sh + (local) vagrant@vitess:/vagrant/src/vitess.io/vitess$ vagrant-scripts/vitess/start.sh + ``` + **注意:**这将启动一个完整的Vitess集群，其中包含一个分片和五个tablet。 + +2. **连接到VTGate** + + + 在VM上，您可以使用MySQL协议使用以下命令连接到VTGate + + ```sh + mysql -umysql_user -pmysql_password -h vitess -P 15306 + ``` + 有一个消息表可供您使用： + + ```sh + mysql> select count(*) from messages; + +----------+ + | count(*) | + +----------+ + | 0 | + +----------+ + 1 row in set (0.01 sec) + ``` + + 此外，vtgate管理UI可通过 http://localhost:15001 访问 + +3. **连接到Vtctld** + + Vitess集群管理控制UI可通过 http://localhost:15000访问 + + +### 运行客户端应用程序 + +`client.py`文件是一个简单的示例应用程序，它连接到`vtgate`并执行一些查询。要运行它，您需要 + +* 使用`client.sh`脚本，它会设置临时环境，然后运行`client.py`。 + + + ```sh + export VTROOT=/vagrant + export VTDATAROOT=/tmp/vtdata-dev + export MYSQL_FLAVOR=MySQL56 + cd "$VITESS_WORKSPACE"/examples/local + ./client.sh + ### example output: + # Inserting into master... + # Reading from master... + # (5L, 1462510331910124032L, 'V is for speed') + # (15L, 1462519383758071808L, 'V is for speed') + # (42L, 1462510369213753088L, 'V is for speed') + # ... + ``` +Java，PHP和Go的同一目录中也有客户端示例。有关使用说明，请参阅每个示例文件顶部的注释。 + +### 拆除集群 + +完成测试后，可以使用以下脚本拆除群集： + +```sh +(local) vagrant@vitess:/vagrant/src/vitess.io/vitess$ vagrant-scripts/vitess/stop.sh +``` + +## 故障排除 + +如果出现任何问题，请检查`$VTDATAROOT/tmp`目录中的日志以获取错误消息。还有一些特定于平板电脑的日志，以及各种 `$VTDATAROOT/vt_*`目录下的MySQL日志。 + +如果您需要帮助来诊断问题，请发送消息到我们的[Slack channel](https://vitess.slack.com)。除了您在命令行中看到的任何错误之外，还可以将`VTDATAROOT`目录的存档上传到文件共享服务并提供指向它的链接。 + diff --git a/content/zh/docs/19.0/launching/_index.md b/content/zh/docs/19.0/launching/_index.md new file mode 100644 index 000000000..ca01bd58d --- /dev/null +++ b/content/zh/docs/19.0/launching/_index.md @@ -0,0 +1,10 @@ +--- +title: Launching +description: Everything you need to know to launch your project with Vitess +weight: 7 +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} + +This section seeks to outline everything you need to launch your project successfully with Vitess. It will be updated with additional documentation. diff --git a/content/zh/docs/19.0/launching/production-planning.md b/content/zh/docs/19.0/launching/production-planning.md new file mode 100644 index 000000000..9ae75fbf3 --- /dev/null +++ b/content/zh/docs/19.0/launching/production-planning.md @@ -0,0 +1,68 @@ +--- +title: Production Planning +weight: 2 +--- + +## Provisioning + +### Estimating total resources + +Although Vitess helps you scale indefinitely, the various layers do consume CPU and memory. Currently, the cost of Vitess servers is dominated by the RPC framework which we use: gRPC (gRPC is a relatively young product). So, Vitess servers are expected to get more efficient over time as there are improvements in gRPC as well as the Go runtime. For now, you can use the following rules of thumb to budget resources for Vitess: + +Every MySQL instance that serves traffic requires one VTTablet, which is in turn expected to consume an equal amount of CPU. So, if MySQL consumes 8 CPUs, VTTablet is likely going to consume another 8. + +The memory consumed by VTTablet depends on QPS and result size, but you can start off with the rule of thumb of requesting 1 GB/CPU. + +As for VTGate, double the total number of CPUs you’ve allocated for VTTablet. That should be approximately how much the VTGates are expected to consume. In terms of memory, you should again budget about 1 GB/CPU (needs verification). + +Vitess servers will use disk space for their logs. A smoothly running server should create very little log spam. However, log files can grow big very quickly if there are too many errors. It will be wise to run a log purger daemon if you’re concerned about filling up disk. + +Vitess servers are also likely to add about 2 ms of round-trip latency per MySQL call. This may result in some hidden costs that may or may not be negligible. On the app side, if a significant time is spent making database calls, then you may have to run additional threads or workers to compensate for the delay, which may result in additional memory requirements. + +The client driver CPU usage may be different from a normal MySQL driver. That may require you to allocate more CPU per app thread. + +On the server side, this could result in longer running transactions, which could weigh down MySQL. + +With the above numbers as starting point, the next step will be to set up benchmarks that generate production representative load. If you cannot afford this luxury, you may have to go into production with some over-provisioning, just in case. + +### Mapping topology to hardware + +The different Vitess components have different resource requirements e.g. vtgate requires little disk in comparison to vttablet. Therefore, the components should be mapped to different machine classes for optimal resource usage. If you’re using a cluster manager (such as Kubernetes), the automatic scheduler will do this for you. Otherwise, you have to allocate physical machines and plan out how you’re going to map servers onto them. + +Machine classes needed: + +#### MySQL + vttablet + +You’ll need database-class machines that are likely to have SSDs, and enough RAM to fit the MySQL working set in buffer cache. Make sure that there will be sufficient CPU left for VTTablet to run on them. + +The VTTablet provisioning will be dictated by the MySQL instances they run against. However, soon after launch, it’s recommended to shard these instances to a data size of 100-300 GB. This should also typically reduce the per-MySQL CPU usage to around 2-4 CPUS depending on the load pattern. + +#### VTGate + +For VTGates, you’ll need a class of machines that would be CPU heavy, but may be light on memory usage, and should require normal hard disks, for binary and logs only. + +It’s advisable to run more instances than there are machines. VTGates are happiest when they’re consuming between 2-4 CPUs. So, if your total requirement was 400 CPUs, and your VTGate class machine has 48 cores each, you’ll need about 10 such machines and you’ll be running about 10 VTGates per box. + +You may have to add a few more app class machines to absorb any additional CPU and latency overheads. + +## Lock service setup + +The Lock Service should be running, and both the global and local instances should be up. See the [Topology Service](../../user-guides/topology-service) document for more information. + +Each lock service implementation supports a couple configuration command line parameters, they need to be specified for each Vitess process. + +For sizing purposes, the Vitess processes do not access the lock service very much. Each *vtgate* process keeps a few watches on a few local nodes (`VSchema` and `SrvKeyspace`). Each *vttablet* process will keep its own Tablet record up to date, but it usually doesn't change. The *vtctld* process will access it a lot more, but only on demand to display web pages. + +As mentioned previously, if the setup is only in one cell, the global and local instances can be combined. Just use different top-level directories. + +## Production testing + +Before running Vitess in production, please make yourself comfortable first with the different operations. We recommend to go through the following scenarios on a non-production system. + +Here is a short list of all the basic workflows Vitess supports: + +* [Failover](../../user-guides/upgrading/) / [Reparents](../../user-guides/reparenting/) +* [Backup/Restore](../../user-guides/backup-and-restore) +* [Schema Management](../../schema-management) / [Schema Swap](../../schema-management/schema-swap) +* [Resharding](../../sharding/#resharding) / [Horizontal Resharding Tutorial](../../get-started/local/) +* [Upgrading](../../user-guides/upgrading) diff --git a/content/zh/docs/19.0/launching/scalability-philosophy.md b/content/zh/docs/19.0/launching/scalability-philosophy.md new file mode 100644 index 000000000..682844d5f --- /dev/null +++ b/content/zh/docs/19.0/launching/scalability-philosophy.md @@ -0,0 +1,160 @@ +--- +title: Scalability Philosophy +weight: 1 +--- + +Scalability problems can be solved using many approaches. This document describes Vitess’ approach to address these problems. + +## Small instances + +When deciding to shard or break databases up into smaller parts, it’s tempting to break them just enough that they fit in one machine. In the industry, it’s common to run only one MySQL instance per host. + +Vitess recommends that instances be broken up to be even smaller, and not to shy away from running multiple instances per host. The net resource usage would be about the same. But the manageability greatly improves when MySQL instances are small. There is the complication of keeping track of ports, and separating the paths for the MySQL instances. However, everything else becomes simpler once this hurdle is crossed. + +There are fewer lock contentions to worry about, replication is a lot happier, production impact of outages become smaller, backups and restores run faster, and a lot more secondary advantages can be realized. For example, you can shuffle instances around to get better machine or rack diversity leading to even smaller production impact on outages, and improved resource usage. + +### Cloud Vs Baremetal + +Although Vitess is designed to run in the cloud, it is entirely possible to run it on baremetal configs, and many users still do. If deploying in a cloud, the assignment of servers and ports is abstracted away from the administrator. On baremetal, the operator still has these responsibilities. + +We provide sample configs to help you [get started on Kubernetes](../../tutorials/kubernetes) since it's the most similar to Borg (the [predecessor to Kubernetes](https://kubernetes.io/blog/2015/04/borg-predecessor-to-kubernetes/) on which Vitess now runs in YouTube). If you're more familiar with alternatives like Mesos, Swarm, Nomad, or DC/OS, we'd welcome your contribution of sample configs for Vitess. + +These orchestration systems typically use [containers](https://en.wikipedia.org/wiki/Software_container) to isolate small instances so they can be efficiently packed onto machines without contention on ports, paths, or compute resources. Then an automated scheduler does the job of shuffling instances around for failure resilience and optimum utilization. + +## Durability through replication + +Traditional data storage software treated data as durable as soon as it was flushed to disk. However, this approach is impractical in today’s world of commodity hardware. Such an approach also does not address disaster scenarios. + +The new approach to durability is achieved by copying the data to multiple machines, and even geographical locations. This form of durability addresses the modern concerns of device failures and disasters. + +Many of the workflows in Vitess have been built with this approach in mind. For example, turning on semi-sync replication is highly recommended. This allows Vitess to failover to a new replica when a master goes down, with no data loss. Vitess also recommends that you avoid recovering a crashed database. Instead, create a fresh one from a recent backup and let it catch up. + +Relying on replication also allows you to loosen some of the disk-based durability settings. For example, you can turn off `sync_binlog`, which greatly reduces the number of IOPS to the disk thereby increasing effective throughput. + +## Consistency model + +Before sharding or moving tables to different keyspaces, the application needs to be verified (or changed) such that it can tolerate the following changes: + +* Cross-shard reads may not be consistent with each other. Conversely, the sharding decision should also attempt to minimize such occurrences because cross-shard reads are more expensive. +* In "best-effort mode", cross-shard transactions can fail in the middle and result in partial commits. You could instead use "2PC mode" transactions that give you distributed atomic guarantees. However, choosing this option increases the write cost by approximately 50%. + +Single shard transactions continue to remain ACID, just like MySQL supports it. + +If there are read-only code paths that can tolerate slightly stale data, the queries should be sent to REPLICA tablets for OLTP, and RDONLY tablets for OLAP workloads. This allows you to scale your read traffic more easily, and gives you the ability to distribute them geographically. + +This tradeoff allows for better throughput at the expense of stale or possible inconsistent reads, since the reads may be lagging behind the master, as data changes (and possibly with varying lag on different shards). To mitigate this, VTGates are capable of monitoring replica lag and can be configured to avoid serving data from instances that are lagging beyond X seconds. + +For true snapshot, the queries must be sent to the master within a transaction. For read-after-write consistency, reading from the master without a transaction is sufficient. + +To summarize, these are the various levels of consistency supported: + +* `REPLICA/RDONLY` read: Servers be scaled geographically. Local reads are fast, but can be stale depending on replica lag. +* `MASTER` read: There is only one worldwide master per shard. Reads coming from remote locations will be subject to network latency and reliability, but the data will be up-to-date (read-after-write consistency). The isolation level is READ_COMMITTED. +* `MASTER` transactions: These exhibit the same properties as MASTER reads. However, you get REPEATABLE_READ consistency and ACID writes for a single shard. Support is underway for cross-shard Atomic transactions. + +As for atomicity, the following levels are supported: + +* `SINGLE`: disallow multi-db transactions. +* `MULTI`: multi-db transactions with best effort commit. +* `TWOPC`: multi-db transactions with 2pc commit. + +### No multi-master + +Vitess doesn’t support multi-master setup. It has alternate ways of addressing most of the use cases that are typically solved by multi-master: + +* Scalability: There are situations where multi-master gives you a little bit of additional runway. However, since the statements have to eventually be applied to all masters, it’s not a sustainable strategy. Vitess addresses this problem through sharding, which can scale indefinitely. +* High availability: Vitess integrates with Orchestrator, which is capable of performing a failover to a new master within seconds of failure detection. This is usually sufficient for most applications. +* Low-latency geographically distributed writes: This is one case that is not addressed by Vitess. The current recommendation is to absorb the latency cost of long-distance round-trips for writes. If the data distribution allows, you still have the option of sharding based on geographic affinity. You can then setup masters for different shards to be in different geographic location. This way, most of the master writes can still be local. + +### Big data queries + +There are two main ways to access the data for offline data processing (as opposed to online web or direct access to the live data): sending queries to rdonly servers, or using a Map Reduce framework. + +#### Batch queries + +These are regular queries, but they can consume a lot of data. Typically, the streaming APIs are used, to consume large quantities of data. + +These queries are just sent to the `rdonly` servers (also known as *batch* servers). They can take as much resources as they want without affecting live traffic. + +#### MapReduce + +Vitess supports MapReduce access to the data. Vitess provides a Hadoop connector, that can also be used with Apache Spark. See the [Hadoop package documentation](https://github.com/vitessio/vitess/tree/master/java/hadoop/src/main/java/io/vitess/hadoop) for more information. + +With a MapReduce framework, Vitess does not support very complicated queries. In part because it would be difficult and not very efficient, but also because the MapReduce frameworks are usually very good at data processing. So instead of doing very complex SQL queries and have processed results, it is recommended to just dump the input data out of Vitess (with simple select statements), and process it with a MapReduce pipeline. + +## Multi-cell + +Vitess is meant to run in multiple data centers / regions / cells. In this part, we'll use cell as a set of servers that are very close together, and share the same regional availability. + +A cell typically contains a set of tablets, a vtgate pool, and app servers that use the Vitess cluster. With Vitess, all components can be configured and brought up as needed: + +* The master for a shard can be in any cell. If cross-cell master access is required, vtgate can be configured to do so easily (by passing the cell that contains the master as a cell to watch). +* It is not uncommon to have the cells that can contain the master be more provisioned than read-only serving cells. These *master-capable* cells may need one more replica to handle a possible failover, while still maintaining the same replica serving capacity. +* Failing over from one master in one cell to a master in a different cell is no different than a local failover. It has an implication on traffic and latency, but if the application traffic also gets re-directed to the new cell, the end result is stable. +* It is also possible to have some shards with a master in one cell, and some other shards with their master in another cell. vtgate will just route the traffic to the right place, incurring extra latency cost only on the remote access. For instance, creating U.S. user records in a database with masters in the U.S. and European user records in a database with masters in Europe is easy to do. Replicas can exist in every cell anyway, and serve the replica traffic quickly. +* Replica serving cells are a good compromise to reduce user-visible latency: they only contain replica servers, and master access is always done remotely. If the application profile is mostly reads, this works really well. +* Not all cells need `rdonly` (or batch) instances. Only the cells that run batch jobs, or MapReduce jobs, really need them. + +Note Vitess uses local-cell data first, and is very resilient to any cell going down (most of our processes handle that case gracefully). + +## Lock server + +Vitess is a highly available service, and Vitess itself needs to store a small amount of metadata very reliably. For that purpose, Vitess needs a highly available and consistent data store. + +Lock servers were built for this exact purpose, and Vitess needs one such cluster to be setup to run smoothly. Vitess can be customized to utilize any lock server, and by default it supports Zookeeper, etcd and Consul. We call this component [Topology Service](../../user-guides/topology-service). + +As Vitess is meant to run in multiple data centers / regions (called cells below), it relies on two different lock servers: + +* global instance: it contains global meta data, like the list of Keyspaces / Shards, the VSchema, ... It should be reliable and distributed across multiple cells. Running Vitess processes almost never access the global instance. +* per-cell instance (local): It should be running only in the local cell. It contains aggregates of all the global data, plus local running tablet information. Running Vitess processes get most of their topology data from the local instance. + +This separation is key to higher reliability. A single cell going bad is never critical for Vitess, as the global instance is configured to survive it, and other cells can take over the production traffic. The global instance can be unavailable for minutes and not affect serving at all (it would affect VSchema changes for instance, but these are not critical, they can wait for the global instance to be back). + +If Vitess is only running in one cell, both global and local instances can share the same lock service instance. It is always possible to split them later when expanding to multiple cells. + +## Monitoring + +The most stressful part of running a production system is the situation where one is trying to troubleshoot an ongoing outage. You have to be able to get to the root cause quickly and find the correct remedy. This is one area where monitoring becomes critical and Vitess has been battle-tested. A large number of internal state variables and counters are continuously exported by Vitess through the /debug/vars and other URLs. There’s also work underway to integrate with third party monitoring tools like Prometheus. + +Vitess errs on the side of over-reporting, but you can be picky about which of these variables you want to monitor. It’s important and recommended to plot graphs of this data because it’s easy to spot the timing and magnitude of a change. It’s also essential to set up various threshold-based alerts that can be used to proactively prevent outages. + +## Development workflow + +Vitess provides binaries and scripts to make unit testing of the application code very easy. With these tools, we recommend to unit test all the application features if possible. + +A production environment for a Vitess cluster involves a topology service, multiple database instances, a vtgate pool and at least one vtctld process, possibly in multiple data centers. The vttest library uses the *vtcombo* binary to combine all the Vitess processes into just one. The various databases are also combined into a single MySQL instance (using different database names for each shard). The database schema is initialized at startup. The (optional) VSchema is also initialized at startup. + +A few things to consider: + +* Use the same database schema in tests as the production schema. +* Use the same VSchema in tests as the production VSchema. +* When a production keyspace is sharded, use a sharded test keyspace as well. Just two shards is usually enough, to minimize test startup time, while still re-producing the production environment. +* *vtcombo* can also start the vtctld component, so the test environment is visible with the Vitess UI. +* See [vttest.proto](https://github.com/vitessio/vitess/blob/master/proto/vttest.proto) for more information. + +## Application query patterns + +Although Vitess strives to minimize the app changes required to scale, there are some important considerations for application queries. + +### Commands specific to single MySQL instances + +Since vitess represents a combined view of all MySQL instances, there are some operations it cannot reasonably perform in a backward compatible manner. For example: + +* `SET GLOBAL` +* `SHOW` +* Binary log commands +* Other single keyspace administrative commands + +However, Vitess allows you to target a single MySQL instance through an extended syntax of the USE statement. If so, it will allow you to execute some of these statements as pass-through. + +### Connecting to Vitess + +If your application previously connected to master or replica instances through different hosts and ports, those parts will have to be changed to connect to a single load-balanced IP. + +Instead, the database type will be specified as part of the db name. For example, to connect to a master, you would specify the dbname as `db@master`. For a replica, it would be `db@replica`. + +### Query support + +A sharded Vitess is not 100% backward compatible with MySQL. Some queries that used to work will cease to work. It’s important that you run all your queries on a sharded test environment -- see the [Development workflow](#development-workflow) section above -- to make sure none will fail on production. + +Our goal is to expand query support based on the needs of users. If you encounter an important construct that isn't supported, please create or comment on an existing feature request so we know how to prioritize. diff --git a/content/zh/docs/19.0/launching/server-configuration.md b/content/zh/docs/19.0/launching/server-configuration.md new file mode 100644 index 000000000..279967cf0 --- /dev/null +++ b/content/zh/docs/19.0/launching/server-configuration.md @@ -0,0 +1,558 @@ +--- +title: Server Configuration +weight: 3 +--- + +## MySQL + +Vitess has some requirements on how MySQL should be configured. These will be detailed below. + +As a reminder, semi-sync replication is highly recommended. It offers a much better durability story than relying on a disk. This will also let you relax the disk-based durability settings. + +### Versions + +MySQL versions supported are: MariaDB 10.0, MySQL 5.6 and MySQL 5.7. A number of custom versions based on these exist (Percona, …), Vitess most likely supports them if the version they are based on is supported. + +### Config files + +#### my.cnf + +The main my.cnf file is generated by mysqlctl init based primarily on $VTROOT/config/mycnf/default.cnf. Additional files will be appended to the generated my.cnf as specified in a colon-separated list of absolute paths in the EXTRA\_MY\_CNF environment variable. For example, this is typically used to include flavor-specific config files. + +To customize the my.cnf, you can either add overrides in an additional EXTRA\_MY\_CNF file, or modify the files in $VTROOT/config/mycnf before distributing to your servers. In Kubernetes, you can use a ConfigMap to overwrite the entire $VTROOT/config/mycnf directory with your custom versions, rather than baking them into a custom container image. + +#### init\_db.sql + +When a new instance is initialized with mysqlctl init (as opposed to restarting in a previously initialized data dir with mysqlctl start), the init\_db.sql file is applied to the server immediately after executing mysql\_install\_db. By default, this file contains the equivalent of running mysql\_secure\_installation, as well as the necessary tables and grants for Vitess. + +If you are running Vitess on top of an existing MySQL instance, rather than using mysqlctl, you can use this file as a sample of what grants need to be applied to enable Vitess. + +Note that changes to this file will not be reflected in shards that have already been initialized and had at least one backup taken. New instances in such shards will automatically restore the latest backup upon vttablet startup, overwriting the data dir created by mysqlctl. + +### Row-Based replication (RBR) + +Most Vitess features rely on MySQL being configured to use row-based replication, with `binlog_row_image` set to `full`. + +### Data types + +Vitess supports all data types including newer data types like spatial and JSON. + +### No side effects + +Vitess cannot guarantee data consistency if the schema contains constructs with side effects. These are triggers, stored procedures and foreign keys. + +This rule is not strictly enforced. You are allowed to add these things, but at your own risk. As long as you’ve ensured that a certain side-effect will not break Vitess, you can add it to the schema. + +It’s safe to apply backward compatible DDLs directly to MySQL. VTTablets can be configured to periodically check the schema for changes. + +### Autocommit + +MySQL autocommit needs to be turned on. + +VTTablet uses connection pools to MySQL. If autocommit was turned off, MySQL will start an implicit transaction (with a point in time snapshot) for each connection and will work very hard at keeping the current view unchanged, which would be counter-productive. + +### Safe startup + +We recommend to enable read-only and skip-slave-start at startup. The first ensures that writes will not be accepted accidentally, which could cause split brain or alternate futures. The second ensures that slaves do not connect to the master before settings like semisync are initialized by vttablet according to Vitess-specific logic. + +### Binary logging + +By default, we enable binary logging everywhere (log-bin), including on slaves (log-slave-updates). On replica type tablets, this is important to make sure they have the necessary binlogs in case they are promoted to master. The slave binlogs are also used to implement Vitess features like VReplication. + +### Global Transaction ID (GTID) + +Many features of Vitess require a fully GTID-based MySQL replication topology, including master management and VReplication. + +For MySQL 5.6+, that means you must use gtid\_mode=ON on all servers. We also strongly encourage enforce\_gtid\_consistency. + +Similarly, for MariaDB, you should use gtid\_strict\_mode to ensure that master management operations will fail rather than risk causing data loss if slaves diverge from the master due to external interference. + +### Monitoring + +In addition to monitoring the Vitess processes, we recommend to monitor MySQL as well. Here is a list of MySQL metrics you should monitor: + +* QPS +* Bytes sent/received +* Replication lag +* Threads running +* Innodb buffer cache hit rate +* CPU, memory and disk usage. For disk, break into bytes read/written, latencies and IOPS. + +### Recap + +* 2-4 cores +* 100-300GB data size +* Row based replication (required) +* Semi-sync replication + * `rpl_semi_sync_master_timeout` is huge (essentially never; there's no way to actually specify never) + * `rpl_semi_sync_master_wait_no_slave = 1` +* `autocommit` ON (required) +* Additional parameters as mentioned in above sections. + +## Vitess servers + +Vitess servers are written in Go. There are a few Vitess-specific knobs that apply to all servers. + +### Go version + +Go, being a young language, tends to add major improvements over each version. So, the latest Go version is almost always recommended. Note that the latest Go version may be higher than the minimum version we require for compiling the binaries (see ["Prerequisites" section in the Getting Started guide](../../get-started/kubernetes/#prerequisites)). + +### GOMAXPROCS + +You typically don’t have to set this environment variable. The default Go runtime will try to use as much CPU as necessary. However, if you want to force a Go server to not exceed a certain CPU limit, setting GOMAXPROCS to that value will work in most situations. + +### GOGC + +The default value for this variable is 100. Which means that garbage is collected every time memory doubles from the baseline (100% growth). You typically don’t have to change this value either. However, if you care about tail latency, increasing this value will help you in that area, but at the cost of increased memory usage. + +### Logging + +Vitess servers write to log files, and they are rotated when they reach a maximum size. It’s recommended that you run at INFO level logging. The information printed in the log files come in handy for troubleshooting. You can limit the disk usage by running cron jobs that periodically purge or archive them. + +Vitess supports both MySQL protocol and gRPC for communication between client and Vitess and uses gRPC for communication between Vitess servers. By default, Vitess does not use SSL. + +Also, even without using SSL, we allow the use of an application-provided CallerID object. It allows unsecure but easy to use authorization using Table ACLs. + +See the [Transport Security Model](../../user-guides/transport-security-model) document for more information on how to setup both of these features, and what command line parameters exist. + +### Topology Service configuration + +Vttablet, vtgate, vtctld need the right command line parameters to find the Topology Server. First the topo\_implementation flag needs to be set to one of zk2, etcd2, or consul. Then they're all configured as follows: + +* The topo_global_server_address contains the server address / addresses of the global topology server. +* The topo_global_root contains the directory / path to use. + +Note that the local cell for the tablet must exist and be configured properly in the Topology Service for vttablet to start. Local cells are configured inside the topo server, by using the vtctl AddCellInfo command. See the Topology Service documentation for more information. + +## VTTablet + +VTTablet has a large number of command line options. Some important ones will be covered here. In terms of provisioning these are the recommended values + +* 2-4 cores (in proportion to MySQL cores) +* 2-4 GB RAM + +### Directory Configuration + +vttablet supports a number of command line options and environment variables to facilitate its setup. + +The VTDATAROOT environment variable specifies the toplevel directory for all data files. If not set, it defaults to /vt. + +By default, a vttablet will use a subdirectory in VTDATAROOT named vt\_NNNNNNNNNN where NNNNNNNNNN is the tablet id. The tablet\_dir command-line parameter allows overriding this relative path. This is useful in containers where the filesystem only contains one vttablet, in order to have a fixed root directory. + +When starting up and using mysqlctl to manage MySQL, the MySQL files will be in subdirectories of the tablet root. For instance, bin-logs for the binary logs, data for the data files, and relay-logs for the relay logs. + +It is possible to host different parts of a MySQL server files on different partitions. For instance, the data file may reside in flash, while the bin logs and relay logs are on spindle. To achieve this, create a symlink from $VTDATAROOT/\ to the proper location on disk. When MySQL is configured by mysqlctl, it will realize this directory exists, and use it for the files it would otherwise have put in the tablet directory. For instance, to host the binlogs in /mnt/bin-logs: + +* Create a symlink from $VTDATAROOT/bin-logs to /mnt/bin-logs. +* When starting up a tablet: + * /mnt/bin-logs/vt\_NNNNNNNNNN will be created. + * $VTDATAROOT/vt\_NNNNNNNNNN/bin-logs will be a symlink to /mnt/bin-logs/vt\_NNNNNNNNNN + +### Initialization + +* Init\_keyspace, init\_shard, init\_tablet\_type: These parameters should be set at startup with the keyspace / shard / tablet type to start the tablet as. Note ‘master’ is not allowed here, instead use ‘replica’, as the tablet when starting will figure out if it is the master (this way, all replica tablets start with the same command line parameters, independently of which one is the master). + +### Query server parameters + +* **queryserver-config-pool-size**: This value should typically be set to the max number of simultaneous queries you want MySQL to run. This should typically be around 2-3x the number of allocated CPUs. Around 4-16. There is not much harm in going higher with this value, but you may see no additional benefits. +* **queryserver-config-stream-pool-size**: This value is relevant only if you plan to run streaming queries against the database. It’s recommended that you use rdonly instances for such streaming queries. This value depends on how many simultaneous streaming queries you plan to run. Typical values are in the low 100s. +* **queryserver-config-transaction-cap**: This value should be set to how many concurrent transactions you wish to allow. This should be a function of transaction QPS and transaction length. Typical values are in the low 100s. +* **queryserver-config-query-timeout**: This value should be set to the upper limit you’re willing to allow a query to run before it’s deemed too expensive or detrimental to the rest of the system. VTTablet will kill any query that exceeds this timeout. This value is usually around 15-30s. +* **queryserver-config-transaction-timeout**: This value is meant to protect the situation where a client has crashed without completing a transaction. Typical value for this timeout is 30s. +* **queryserver-config-max-result-size**: This parameter prevents the OLTP application from accidentally requesting too many rows. If the result exceeds the specified number of rows, VTTablet returns an error. The default value is 10,000. + +### DB config parameters + +VTTablet requires multiple user credentials to perform its tasks. Since it's required to run on the same machine as MySQL, it’s most beneficial to use the more efficient unix socket connections. + +**connection** parameters + +* `db_socket`: The unix socket to connect on. If this is specified, host and port will not be used. +* `db_host`: The host name for the tcp connection. +* `db_port`: The tcp port to be used with the `db_host`. +* `db_charset`: Character set. Only utf8 or latin1 based character sets are supported. +* `db_flags`: Flag values as defined by MySQL. +* `db_ssl_ca`, `db_ssl_ca_path`, `db_ssl_cert`, `db_ssl_key`: SSL flags. + +**app** credentials are for serving app queries: + +* `db_app_user`: App username. +* `db_app_password`: Password for the app username. If you need a more secure way of managing and supplying passwords, VTTablet does allow you to plug into a "password server" that can securely supply and refresh usernames and passwords. Please contact the Vitess team for help if you’d like to write such a custom plugin. +* `db_app_use_ssl`: Set this flag to false if you don't want to use SSL for this connection. This will allow you to turn off SSL for all users except for `repl`, which may have to be turned on for replication that goes over open networks. + +**appdebug** credentials are for the appdebug user: + +* `db_appdebug_user` +* `db_appdebug_password` +* `db_appdebug_use_ssl` + +**dba** credentials will be used for housekeeping work like loading the schema or killing runaway queries: + +* `db_dba_user` +* `db_dba_password` +* `db_dba_use_ssl` + +**repl** credentials are for managing replication. + +* `db_repl_user` +* `db_repl_password` +* `db_repl_use_ssl` + +**filtered** credentials are for VReplication streams when copying data: + +* `db_filtered_user` +* `db_filtered_password` +* `db_filtered_use_ssl` + +### Monitoring + +VTTablet exports a wealth of real-time information about itself. This section will explain the essential ones: + +#### /debug/status + +This page has a variety of human-readable information about the current VTTablet. You can look at this page to get a general overview of what’s going on. It also has links to various other diagnostic URLs below. + +#### /debug/vars + +This is the most important source of information for monitoring. There are other URLs below that can be used to further drill down. + +#### Queries (as described in /debug/vars section) + +Vitess has a structured way of exporting certain performance stats. The most common one is the Histogram structure, which is used by Queries: + +``` json + "Queries": { + "Histograms": { + "PASS\_SELECT": { + "1000000": 1138196, + "10000000": 1138313, + "100000000": 1138342, + "1000000000": 1138342, + "10000000000": 1138342, + "500000": 1133195, + "5000000": 1138277, + "50000000": 1138342, + "500000000": 1138342, + "5000000000": 1138342, + "Count": 1138342, + "Time": 387710449887, + "inf": 1138342 + } + }, + "TotalCount": 1138342, + "TotalTime": 387710449887 + }, +``` + +The histograms are broken out into query categories. In the above case, "`PASS\_SELECT`" is the only category. An entry like `"500000": 1133195` means that `1133195` queries took under `500000` nanoseconds to execute. + +`Queries.Histograms.PASS\_SELECT.Count` is the total count in the `PASS\_SELECT` category. + +`Queries.Histograms.PASS\_SELECT.Time` is the total time in the `PASS\_SELECT` category. + +`Queries.TotalCount` is the total count across all categories. + +`Queries.TotalTime` is the total time across all categories. + +There are other Histogram variables described below, and they will always have the same structure. + +Use this variable to track: + +* QPS +* Latency +* Per-category QPS. For replicas, the only category will be PASS\_SELECT, but there will be more for masters. +* Per-category latency +* Per-category tail latency + +#### Results + +``` json + "Results": { + "0": 0, + "1": 0, + "10": 1138326, + "100": 1138326, + "1000": 1138342, + "10000": 1138342, + "5": 1138326, + "50": 1138326, + "500": 1138342, + "5000": 1138342, + "Count": 1138342, + "Total": 1140438, + "inf": 1138342 + } +``` + +Results is a simple histogram with no timing info. It gives you a histogram view of the number of rows returned per query. + +#### Mysql + +Mysql is a histogram variable like Queries, except that it reports MySQL execution times. The categories are "Exec" and “ExecStream”. + +In the past, the exec time difference between VTTablet and MySQL used to be substantial. With the newer versions of Go, the VTTablet exec time has been predominantly been equal to the mysql exec time, conn pool wait time and consolidations waits. In other words, this variable has not shown much value recently. However, it’s good to track this variable initially, until it’s determined that there are no other factors causing a big difference between MySQL performance and VTTablet performance. + +#### Transactions + +Transactions is a histogram variable that tracks transactions. The categories are "Completed" and “Aborted”. + +#### Waits + +Waits is a histogram variable that tracks various waits in the system. Right now, the only category is "Consolidations". A consolidation happens when one query waits for the results of an identical query already executing, thereby saving the database from performing duplicate work. + +This variable used to report connection pool waits, but a refactor moved those variables out into the pool related vars. + +#### Errors + +``` json + "Errors": { + "Deadlock": 0, + "Fail": 1, + "NotInTx": 0, + "TxPoolFull": 0 + }, +``` + +Errors are reported under different categories. It’s beneficial to track each category separately as it will be more helpful for troubleshooting. Right now, there are four categories. The category list may vary as Vitess evolves. + +Plotting errors/query can sometimes be useful for troubleshooting. + +VTTablet also exports an InfoErrors variable that tracks inconsequential errors that don’t signify any kind of problem with the system. For example, a dup key on insert is considered normal because apps tend to use that error to instead update an existing row. So, no monitoring is needed for that variable. + +#### InternalErrors + +``` json + "InternalErrors": { + "HungQuery": 0, + "Invalidation": 0, + "MemcacheStats": 0, + "Mismatch": 0, + "Panic": 0, + "Schema": 0, + "StrayTransactions": 0, + "Task": 0 + }, +``` + +An internal error is an unexpected situation in code that may possibly point to a bug. Such errors may not cause outages, but even a single error needs be escalated for root cause analysis. + +#### Kills + +``` json + "Kills": { + "Queries": 2, + "Transactions": 0 + }, +``` + +Kills reports the queries and transactions killed by VTTablet due to timeout. It’s a very important variable to look at during outages. + +#### TransactionPool* + +There are a few variables with the above prefix: + +``` json + "TransactionPoolAvailable": 300, + "TransactionPoolCapacity": 300, + "TransactionPoolIdleTimeout": 600000000000, + "TransactionPoolMaxCap": 300, + "TransactionPoolTimeout": 30000000000, + "TransactionPoolWaitCount": 0, + "TransactionPoolWaitTime": 0, +``` + +* `WaitCount` will give you how often the transaction pool gets full that causes new transactions to wait. +* `WaitTime`/`WaitCount` will tell you the average wait time. +* `Available` is a gauge that tells you the number of available connections in the pool in real-time. `Capacity-Available` is the number of connections in use. Note that this number could be misleading if the traffic is spiky. + +#### Other Pool variables + +Just like `TransactionPool`, there are variables for other pools: + +* `ConnPool`: This is the pool used for read traffic. +* `StreamConnPool`: This is the pool used for streaming queries. + +There are other internal pools used by VTTablet that are not very consequential. + +#### `TableACLAllowed`, `TableACLDenied`, `TableACLPseudoDenied` + +The above three variables table acl stats broken out by table, plan and user. + +#### `QueryPlanCacheSize` + +If the application does not make good use of bind variables, this value would reach the QueryCacheCapacity. If so, inspecting the current query cache will give you a clue about where the misuse is happening. + +#### `QueryCounts`, `QueryErrorCounts`, `QueryRowCounts`, `QueryTimesNs` + +These variables are another multi-dimensional view of Queries. They have a lot more data than Queries because they’re broken out into tables as well as plan. This is a priceless source of information when it comes to troubleshooting. If an outage is related to rogue queries, the graphs plotted from these vars will immediately show the table on which such queries are run. After that, a quick look at the detailed query stats will most likely identify the culprit. + +#### `UserTableQueryCount`, `UserTableQueryTimesNs`, `UserTransactionCount`, `UserTransactionTimesNs` + +These variables are yet another view of Queries, but broken out by user, table and plan. If you have well-compartmentalized app users, this is another priceless way of identifying a rogue "user app" that could be misbehaving. + +#### `DataFree`, `DataLength`, `IndexLength`, `TableRows` + +These variables are updated periodically from information\_schema.tables. They represent statistical information as reported by MySQL about each table. They can be used for planning purposes, or to track unusual changes in table stats. + +* `DataFree` represents `data_free` +* `DataLength` represents `data_length` +* `IndexLength` represents `index_length` +* `TableRows` represents `table_rows` + +#### /debug/health + +This URL prints out a simple "ok" or “not ok” string that can be used to check if the server is healthy. The health check makes sure mysqld connections work, and replication is configured (though not necessarily running) if not master. + +#### /queryz, /debug/query\_stats, /debug/query\_plans, /streamqueryz + +* /debug/query\_stats is a JSON view of the per-query stats. This information is pulled in real-time from the query cache. The per-table stats in /debug/vars are a roll-up of this information. +* /queryz is a human-readable version of /debug/query\_stats. If a graph shows a table as a possible source of problems, this is the next place to look at to see if a specific query is the root cause. +* /debug/query\_plans is a more static view of the query cache. It just shows how VTTablet will process or rewrite the input query. +* /streamqueryz lists the currently running streaming queries. You have the option to kill any of them from this page. + +#### /querylogz, /debug/querylog, /txlogz, /debug/txlog + +* /debug/querylog is a never-ending stream of currently executing queries with verbose information about each query. This URL can generate a lot of data because it streams every query processed by VTTablet. The details are as per this function: https://github.com/vitessio/vitess/blob/master/go/vt/vttablet/tabletserver/tabletenv/logstats.go#L202 +* /querylogz is a limited human readable version of /debug/querylog. It prints the next 300 queries by default. The limit can be specified with a limit=N parameter on the URL. +* /txlogz is like /querylogz, but for transactions. +* /debug/txlog is the JSON counterpart to /txlogz. + +#### /consolidations + +This URL has an MRU list of consolidations. This is a way of identifying if multiple clients are spamming the same query to a server. + +#### /schemaz, /debug/schema + +* /schemaz shows the schema info loaded by VTTablet. +* /debug/schema is the JSON version of /schemaz. + +#### /debug/query\_rules + +This URL displays the currently active query blacklist rules. + +### Alerting + +Alerting is built on top of the variables you monitor. Before setting up alerts, you should get some baseline stats and variance, and then you can build meaningful alerting rules. You can use the following list as a guideline to build your own: + +* Query latency among all vttablets +* Per keyspace latency +* Errors/query +* Memory usage +* Unhealthy for too long +* Too many vttablets down +* Health has been flapping +* Transaction pool full error rate +* Any internal error +* Traffic out of balance among replicas +* Qps/core too high + +## VTGate + +A typical VTGate should be provisioned as follows. + +* 2-4 cores +* 2-4 GB RAM + +Since VTGate is stateless, you can scale it linearly by just adding more servers as needed. Beyond the recommended values, it’s better to add more VTGates than giving more resources to existing servers, as recommended in the philosophy section. + +Load-balancer in front of vtgate to scale up (not covered by Vitess). Stateless, can use the health URL for health check. + +### Parameters + +* `cells_to_watch`: which cell vtgate is in and will monitor tablets from. Cross-cell master access needs multiple cells here. +* `tablet_types_to_wait`: VTGate waits for at least one serving tablet per tablet type specified here during startup, before listening to the serving port. So VTGate does not serve error. It should match the available tablet types VTGate connects to (master, replica, rdonly). +* `discovery_low_replication_lag`: when replication lags of all VTTablet in a particular shard and tablet type are less than or equal the flag (in seconds), VTGate does not filter them by replication lag and uses all to balance traffic. +* `degraded_threshold (30s)`: a tablet will publish itself as degraded if replication lag exceeds this threshold. This will cause VTGates to choose more up-to-date servers over this one. If all servers are degraded, VTGate resorts to serving from all of them. +* `unhealthy_threshold (2h)`: a tablet will publish itself as unhealthy if replication lag exceeds this threshold. +* `transaction_mode (multi)`: single: disallow multi-db transactions, multi: allow multi-db transactions with best effort commit, twopc: allow multi-db transactions with 2pc commit. +* `normalize_queries (false)`: Turning this flag on will cause vtgate to rewrite queries with bind vars. This is beneficial if the app doesn't itself send normalized queries. + +### Monitoring + +#### /debug/status + +This is the landing page for a VTGate, which can gives you a status on how a particular server is doing. Of particular interest there is the list of tablets this vtgate process is connected to, as this is the list of tablets that can potentially serve queries. + +#### /debug/vars + +##### VTGateApi + +This is the main histogram variable to track for vtgates. It gives you a break up of all queries by command, keyspace, and type. + +##### HealthcheckConnections + +It shows the number of tablet connections for query/healthcheck per keyspace, shard, and tablet type. + +##### /debug/query\_plans + +This URL gives you all the query plans for queries going through VTGate. + +##### /debug/vschema + +This URL shows the vschema as loaded by VTGate. + +### Alerting + +For VTGate, here’s a list of possible variables to alert on: + +* Error rate +* Error/query rate +* Error/query/tablet-type rate +* VTGate serving graph is stale by x minutes (lock server is down) +* Qps/core +* Latency + +## External processes + +Things that need to be configured: + +### Periodic backup configuration + +We recommend to take backups regularly e.g. you should set up a cron job for it. See our recommendations at [/user-guide/backup-and-restore/#backup-frequency](../../user-guides/backup-and-restore/#backup-frequency). + +### Logs archiver/purger + +You will need to run some cron jobs to archive or purge log files periodically. + +### Orchestrator + +[Orchestrator](https://github.com/github/orchestrator) is a tool for managing MySQL replication topologies, including automated failover. It can detect master failure and initiate a recovery in a matter of seconds. + +For the most part, Vitess is agnostic to the actions of Orchestrator, which operates below Vitess at the MySQL level. That means you can pretty much https://github.com/github/orchestrator/wiki/Orchestrator-Manual[set up Orchestrator](https://github.com/github/orchestrator/wiki/Orchestrator-Manual) in the normal way, with just a few additions as described below. + +For the [Kubernetes](../../tutorials/kubernetes) example, we provide a sample script to launch Orchestrator for you with these settings applied. + +#### Orchestrator configuration + +Orchestrator needs to know some things from the Vitess side, like the tablet aliases and whether semisync is enforced (with async fallback disabled). We pass this information by telling Orchestrator to execute certain queries that return local metadata from a non-replicated table, as seen in our sample [orchestrator.conf.json](https://github.com/vitessio/vitess/blob/master/docker/orchestrator/orchestrator.conf.json): + +``` json +"DetectClusterAliasQuery": "SELECT value FROM _vt.local_metadata WHERE name='ClusterAlias'", +"DetectInstanceAliasQuery": "SELECT value FROM _vt.local_metadata WHERE name='Alias'", +"DetectPromotionRuleQuery": "SELECT value FROM _vt.local_metadata WHERE name='PromotionRule'", +"DetectSemiSyncEnforcedQuery": "SELECT @@global.rpl_semi_sync_master_wait_no_slave AND @@global.rpl_semi_sync_master_timeout > 1000000", +``` + +There is also one thing that Vitess needs to know from Orchestrator, which is the identity of the master for each shard, if a failover occurs. + +From our experience at YouTube, we believe that this signal is too critical for data integrity to rely on bottom-up detection such as asking each MySQL if it thinks it's the master. Instead, we rely on Orchestrator to be the source of truth, and expect it to send a top-down signal to Vitess. + +This signal is sent by ensuring the Orchestrator server has access to vtctlclient, which it then uses to send an RPC to vtctld, informing Vitess of the change in mastership via the [`TabletExternallyReparented`](../../reference/vtctl/#tabletexternallyreparented) command. + +``` json +"PostMasterFailoverProcesses": [ +"echo 'Recovered from {failureType} on {failureCluster}. Failed: {failedHost}:{failedPort}; Promoted: {successorHost}:{successorPort}' >> /tmp/recovery.log", +"vtctlclient -server vtctld:15999 TabletExternallyReparented {successorAlias}" + ], +``` + +#### VTTablet configuration + +Normally, you need to seed Orchestrator by giving it the addresses of MySQL instances in each shard. If you have lots of shards, this could be tedious or error-prone. + +Luckily, Vitess already knows everything about all the MySQL instances that comprise your cluster. So we provide a mechanism for tablets to self-register with the Orchestrator API, configured by the following vttablet parameters: + +* `orc_api_url`: Address of Orchestrator's HTTP API (e.g. http://host:port/api/). Leave empty to disable Orchestrator integration. +* `orc_discover_interval`: How often (e.g. 60s) to ping Orchestrator's HTTP API endpoint to tell it we exist. 0 means never. + +Not only does this relieve you from the initial seeding of addresses into Orchestrator, it also means new instances will be discovered immediately, and the topology will automatically repopulate even if Orchestrator's backing store is wiped out. Note that Orchestrator will forget stale instances after a configurable timeout. diff --git a/content/zh/docs/19.0/launching/troubleshooting.md b/content/zh/docs/19.0/launching/troubleshooting.md new file mode 100644 index 000000000..252809619 --- /dev/null +++ b/content/zh/docs/19.0/launching/troubleshooting.md @@ -0,0 +1,39 @@ +--- +title: Troubleshooting +weight: 5 +--- + +If there is a problem in the system, one or many alerts would typically fire. If a problem was found through means other than an alert, then the alert system needs to be iterated upon. + +When an alert fires, you have the following sources of information to perform your investigation: + +* Alert values +* Graphs +* Diagnostic URLs +* Log files + +Below are a few possible scenarios. + +## Elevated query latency on master + +Diagnosis 1: Inspect the graphs to see if QPS has gone up. If yes, drill down on the more detailed QPS graphs to see which table, or user caused the increase. If a table is identified, look at /debug/queryz for queries on that table. + +Action: Inform engineer about about toxic query. If it’s a specific user, you can stop their job or throttle them to keep the load manageable. As a last resort, blacklist query to allow the rest of the system to stay healthy. + +Diagnosis 2: QPS did not go up, only latency did. Inspect the per-table latency graphs. If it’s a specific table, then it’s most likely a long-running low QPS query that’s skewing the numbers. Identify the culprit query and take necessary steps to get it optimized. Such queries usually do not cause outage. So, there may not be a need to take extreme measures. + +Diagnosis 3: Latency seems to be up across the board. Inspect transaction latency. If this has gone up, then something is causing MySQL to run too many concurrent transactions which causes slow-down. See if there are any tx pool full errors. If there is an increase, the INFO logs will dump info about all transactions. From there, you should be able to if a specific sequence of statements is causing the problem. Once that is identified, find out the root cause. It could be network issues, or it could be a recent change in app behavior. + +Diagnosis 4: No particular transaction seems to be the culprit. Nothing seems to have changed in any of the requests. Look at system variables to see if there are hardware faults. Is the disk latency too high? Are there memory parity errors? If so, you may have to failover to a new machine. + +## Master starts up read-only + +To prevent accidentally accepting writes, our default my.cnf settings tell MySQL to always start up read-only. If the master MySQL gets restarted, it will thus come back read-only until you intervene to confirm that it should accept writes. You can use the `SetReadWrite` command to do that. + +However, usually if something unexpected happens to the master, it's better to reparent to a different replica with `EmergencyReparentShard`. If you need to do planned maintenance on the master, it's best to first reparent to another replica with `PlannedReparentShard`. + +## Vitess sees the wrong tablet as master + +If you do a failover manually (not through Vitess), you'll need to tell Vitess which tablet corresponds to the new master MySQL. Until then, writes will fail since they'll be routed to a read-only replica (the old master). Use the [`TabletExternallyReparented`](link) command to tell Vitess the new master tablet for a shard. + +Tools like [Orchestrator](https://github.com/github/orchestrator) can be configured to call this automatically when a failover occurs. See our sample [orchestrator.conf.json](https://github.com/vitessio/vitess/blob/1129d69282bb738c94b8af661b984b6377a759f7/docker/orchestrator/orchestrator.conf.json#L131) for an example of this. diff --git a/content/zh/docs/19.0/launching/twopc.md b/content/zh/docs/19.0/launching/twopc.md new file mode 100644 index 000000000..85e8189e7 --- /dev/null +++ b/content/zh/docs/19.0/launching/twopc.md @@ -0,0 +1,86 @@ +--- +title: 2PC Overview +weight: 4 +--- + +Vitess 2PC allows you to perform atomic distributed commits. The feature is implemented using traditional MySQL transactions, and hence inherits the same guarantees. With this addition, Vitess can be configured to support the following three levels of atomicity: + +1. **Single database**: At this level, only single database transactions are allowed. Any transaction that tries to go beyond a single database will be failed. +2. **Multi database**: A transaction can span multiple databases, but the commit will be best effort. Partial commits are possible. +3. **2PC**: This is the same as Multi-database, but the commit will be atomic. + +2PC commits are more expensive than multi-database because the system has to save away the statements before starting the commit process, and also clean them up after a successful commit. This is the reason why it's a separate option instead of being always on. + +## Isolation + +2PC transactions guarantee atomicity: either the whole transaction commits, or it's rolled back entirely. It does not guarantee Isolation (in the ACID sense). This means that a third party that performs cross-database reads can observe partial commits while a 2PC transaction is in progress. + +Guaranteeing ACID Isolation is very contentious and has high costs. Providing it by default would have made vitess impractical for the most common use cases. + +### Configuring VTGate + +The atomicity policy is controlled by the transaction_mode flag. The default value is multi, and will set it in multi-database mode. This is the same as the previous legacy behavior. + +To enforce single-database transactions, the VTGates can be started by specifying transaction_mode=single. + +To enable 2PC, the VTGates need to be started with transaction_mode=twopc. The VTTablets will require a few more flags, which will be explained below. + +The VTGate transaction_mode flag decides what to allow. The application can independently request a specific atomicity for each transaction. The request will be honored by VTGate only if it does not exceed what is allowed by the transaction_mode. For example, transaction_mode=single will only allow single-db transactions. On the other hand, transaction_mode=twopc will allow all three levels of atomicity. + +## Driver APIs + +The way to request atomicity from the application is driver-specific. + +### Go driver + +For the Go driver, you request the atomicity by adding it to the context using the WithAtomicity function. For more details, please refer to the respective GoDocs. + +### Python driver + +For Python, the begin function of the cursor has an optional single_db flag. If the flag is True, then the request is for a single-db transaction. If False (or unspecified), then the following commit call's twopc flag decides if the commit is 2PC or Best Effort (multi). + +### Java & PHP (TODO) + +#### Adding support in a new driver + +The VTGate RPC API extends the Begin and Commit functions to specify atomicity. The API mimics the Python driver: The BeginRequest message provides a single_db flag and the CommitRequest message provides an atomic flag which is synonymous to twopc. + +## Configuring VTTablet + +The following flags need to be set to enable 2PC support in VTTablet: + +* **twopc_enable**: This flag needs to be turned on. +* **twopc_coordinator_address**: This should specify the address (or VIP) of the VTGate that VTTablet will use to resolve abandoned transactions. +* **twopc_abandon_age**: This is the time in seconds that specifies how long to wait before asking a VTGate to resolve an abandoned transaction. + +With the above flags specified, every master VTTablet also turns into a watchdog. If any 2PC transaction is left lingering for longer than twopc_abandon_age seconds, then VTTablet invokes VTGate and requests it to resolve it. Typically, the abandon_age needs to be substantially longer than the time it takes for a typical 2PC commit to complete (10s of seconds). + +## Configuring MySQL + +The usual default values of MySQL are sufficient. However, it's important to verify that wait_timeout (28800) has not been changed. If this value was changed to be too short, then MySQL could prematurely kill a prepared transaction causing data loss. + +## Monitoring + +A few additional variables have been added to /debug/vars. Failures described below should be rare. But these variables are present so you can build an alert mechanism if anything were to go wrong. + +## Critical failures + +The following errors are not expected to happen. If they do, it means that 2PC transactions have failed to commit atomically: + +* **InternalErrors.TwopcCommit**: This is a counter that shows the number of times a prepared transaction failed to fulfil a commit request. +* **InternalErrors.TwopcResurrection**: This counter is incremented if a new master failed to resurrect a previously prepared (and unresolved) transaction. + +## Alertable failures + +The following failures are not urgent, but require someone to investigate: + +* **InternalErrors.WatchdogFail**: This counter is incremented if there are failures in the watchdog thread of VTTablet. This means that the watch dog is not able to alert VTGate of abandoned transactions. +* **Unresolved.Prepares**: This is a gauge that is set based on the number of lingering Prepared transactions that have been alive for longer than 5x the abandon age. This usually means that a distributed transaction has repeatedly failed to resolve. A more serious condition is when the metadata for a distributed transaction has been lost and this Prepare is now permanently orphaned. + +## Repairs + +If any of the alerts fire, it's time to investigate. Once you identify the dtid or the VTTablet that originated the alert, you can navigate to the /twopcz URL. This will display three lists: + +* **Failed Transactions**: A transaction reaches this state if it failed to commit. The only action allowed for such transactions is that you can discard it. However, you can record the DMLs that were involved and have someone come up with a plan to repair the partial commit. +* **Prepared Transactions**: Prepared transactions can be rolled back or committed. Prepared transactions must be remedied only if their root Distributed Transaction has been lost or resolved. +* **Distributed Transactions**: Distributed transactions can only be Concluded (marked as resolved). diff --git a/content/zh/docs/19.0/overview/_index.md b/content/zh/docs/19.0/overview/_index.md new file mode 100644 index 000000000..9419c7fd1 --- /dev/null +++ b/content/zh/docs/19.0/overview/_index.md @@ -0,0 +1,10 @@ +--- +title: 概览 +description: Vitess 概述 +weight: 1 +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} + +Vitess概述文档提供了有关Vitess的大致信息， 您可以获得更多的详细信息在[Get Started](../get-started) 章节和 [User Guides](../user-guides)章节. diff --git a/content/zh/docs/19.0/overview/architecture.md b/content/zh/docs/19.0/overview/architecture.md new file mode 100644 index 000000000..a10456030 --- /dev/null +++ b/content/zh/docs/19.0/overview/architecture.md @@ -0,0 +1,55 @@ +--- +title: 架构 +weight: 2 +featured: true +--- + +Vitess平台由许多服务器进程、命令行实用程序和基于Web的实用程序组成，由一致的元数据存储提供支持。 + +根据您当前的业务状态，您可以选择不同的方式最终实现vitess的完整部署。举例来说，如果是从头开始构建服务，那么使用Vitess的第一步就是定义数据库拓扑。如果是扩展现有的数据库， 那么可能需要先部署连接代理。 + +无论您是从一整套数据库开始，还是决定从小规模开始(今后再慢慢扩展)。Vitess工具和服务器都能贴心的帮助到您。对于较小规模的数据库，vttablet功能（如连接池和查询重写）可帮助您从现有硬件中榨取更多性能。对于大规模的数据库，Vitess提供的自动化工具在为更大规模的实施时给予更多的便利。 + +下图说明了Vitess的组件 + +![Vitess Overview Architecture Diagram](../img/VitessOverview.png) + +## Topology + +[拓扑服务](../../user-guides/topology-service) 一个元数据存储，包含有关正在运行的服务器、分片方案和复制图的信息。拓扑由一致的数据存储支持。您可以使用**vtctl** (命令行) 和 **vtctld** (web)查看拓扑. + +在Kubernetes中，数据存储是etcd。 Vitess源代码还附带[Apache ZooKeeper](http://zookeeper.apache.org/)支持。 + +## vtgate + +**vtgate** 是一个轻型代理服务器，它将流量路由到正确的vttablet，并将合并的结果返回给客户端。应用程序向vtgate发起查询。客户端使用起来非常简单，它只需要能够找到vtgate实例就能使vitess。 + +为了路由查询，vtgate综合考虑了分片方案、数据延迟以及vttablet及其对应底层MySQL实例的可用性。 + +## vttablet + +**vttablet** 是一个位于MySQL数据库前面的代理服务器。vitess实现中每个MySQL实例都有一个vttablet。 + +执行的任务试图最大化吞吐量，同时保护mysql不受有害查询的影响。它的特性包括连接池、查询重写和重用重复数据。此外，vtTablet执行vtcl启动的管理任务，并提供用于过滤复制和数据导出的流式服务。 + +通过在MySQL数据库前运行vttablet并更改您的应用程序以使用Vitess客户端而不是MySQL驱动程序，您的应用程序将受益于vttablet的连接池，查询重写和重用数据集等功能。 + +## vtctl + +**vtctl** vtctl是一个用于管理Vitess集群的命令行工具。它允许用户或应用程序轻松地与Vitess实现交互。使用vtctl，您可以识别主数据库和副本数据库，创建表，启动故障转移，执行分片（和重新分片）操作等。 + +当vtctl执行操作时，它会根据需要更lockserver。其他Vitess服务器会观察这些变化并做出相应的反应。例如，如果使用vtctl故障转移到新的主数据库，则vtgate会查看更改并将将写入流量切到新主服务器。 + +## vtctld + +**vtctld** vtctld是一个HTTP服务器，允许您浏览存储在lockserver中的信息。它对于故障排除或获取服务器及其当前状态的高层概观非常有用。 + +## vtworker + +**vtworker** 托管长时间运行的进程。它支持插件架构并提供代码库，以便您可以轻松选择要使用的vttablet。插件可用于以下类型的作业： + +* 水平拆分或合并过程中检查数据的完整性 +* 垂直拆分或合并过程中检查数据的完整性 + +vtworker还可以让您轻松添加其他验证程序。例如，如果一个keyspace中的索引表引用到另一keyspace中的数据，则可以执行片内完整性检查以验证类似外键的关系或跨分片完整性检查。 + diff --git a/content/zh/docs/19.0/overview/cloud-native.md b/content/zh/docs/19.0/overview/cloud-native.md new file mode 100644 index 000000000..1e261d4d1 --- /dev/null +++ b/content/zh/docs/19.0/overview/cloud-native.md @@ -0,0 +1,16 @@ +--- +title: 私有云 +--- + +Vitess非常适合云部署，因为它使数据库能够逐步增加容量。运行Vitess的最简单方法是通过Kubernetes。 + +## Vitess on Kubernetes + +Kubernetes是Docker容器的开源编排系统，Vitess可以作为Kubernetes的云原生分布式数据库运行。 + +Kubernetes负责在计算集群中节点上进行资源调度，并主动管理这些节点的负载。并将包含应用程序的容器分组以便于管理和发现。这为Vitess在YouTube上运行的方式提供了类似的开源环境，这是Kubernetes的前身。 + +**相关的Vitess文档** + +* [Kubernetes 快速入门](../../get-started/kubernetes) + diff --git a/content/zh/docs/19.0/overview/history.md b/content/zh/docs/19.0/overview/history.md new file mode 100644 index 000000000..f37c06271 --- /dev/null +++ b/content/zh/docs/19.0/overview/history.md @@ -0,0 +1,22 @@ +--- +title: 历史 +description: 出生于YouTube, 以开源方式发布 +--- + +自2011年以来，Vitess一直是YouTube基础设施的基本组成部分。本节简要总结了促成Vitess诞生的大事记： + +1. YouTube的MySQL数据库达到了峰值流量很快超过数据库服务容量的程度。为了暂时缓解这个问题，YouTube为写入流量创建了一个主数据库，为读取流量创建了一个副本数据库。 +2. 由于对猫咪视频的需求处于历史最高水平，因此只读流量仍然足以使副本数据库超载。因此，YouTube添加了更多副本，再次提供了临时解决方案。 +3. 最终，写入流量变得太高，主数据库无法处理，要求YouTube对数据进行分片以处理传入流量。（如果数据库的整体大小对于单个MySQL实例来说太大，则也需要进行分片。） +4. YouTube的应用程序层已经过修改，因此在执行任何数据库操作之前，代码可以识别正确的数据库分片以接收该特定查询。 + +vitess使得youtube从源代码中删除该逻辑，在应用程序和数据库之间引入代理来路由和管理数据库交互。 +从那时起，YouTube的用户规模扩大了50倍以上，大大提高了其服务页面、处理新上传视频等的能力。更重要的是，vitess是一个具备无限扩展能力的平台。 + +YouTube选择使用Go语言实现Vitess，因为Go提供了表现力和性能的结合。它几乎和Python一样富有表现力，而且非常易于维护。它的性能与Java相同，在某些情况下接近C++。此外，该语言非常适合并行编程，并且具有非常高质量的标准库。 + +## 开源第一 + +Vitess的开源版本与YouTube上使用的版本非常相似。虽然有一些变化可以让YouTube利用Google的基础架构，但核心功能却是相同的。在开发新功能时，Vitess团队首先确保它们在开源版本中是可以使用的。在某些情况下，团队会编写一个使用Google特定技术的插件。这种方法可确保Vitess的开源版本保持与内部版本相同的质量水平。 + +绝大多数Vitess开发都在GitHub上进行。因此，Vitess在构建时考虑了可扩展性，因此您可以根据基础架构的需要进行调整。 diff --git a/content/zh/docs/19.0/overview/img/VitessOverview.png b/content/zh/docs/19.0/overview/img/VitessOverview.png new file mode 100644 index 000000000..e8e1b17fc Binary files /dev/null and b/content/zh/docs/19.0/overview/img/VitessOverview.png differ diff --git a/content/zh/docs/19.0/overview/whatisvitess.md b/content/zh/docs/19.0/overview/whatisvitess.md new file mode 100644 index 000000000..785d04917 --- /dev/null +++ b/content/zh/docs/19.0/overview/whatisvitess.md @@ -0,0 +1,74 @@ +--- +title: Vitess是什么 +weight: 1 +featured: true +--- + +Vitess是一个用于部署、扩展和管理大型MySQL实例集群的数据库解决方案。Vitess集MySQL数据库的很多重要特性和NoSQL数据库的可扩展性于一体。它的架构设计使得您可以像在物理机上一样在公共云或私有云架构中有效运行。它结合并扩展了许多重要的MySQL功能，同时兼具NoSQL数据库的可扩展性。 +Vitess可以帮助您解决以下问题： + +1. 支持您对MySQL数据库进行分片来扩展MySQL数据库，应用程序无需做太多更改。 +2. 从物理机迁移到私有云或公共云。 +3. 部署和管理大量的MySQL实例。 + +Vitess包括使用与本机查询协议兼容的JDBC和Go数据库驱动。此外，它还实现了MySQL服务器协议，该协议几乎与任何其他语言都兼容。 + +自2011年以来，Vitess一直为YouTube所有的数据库提供服务，现在已被许多企业采用并应用于实际生产。 + +## 特性 + +* 性能提升 + - 连接池 - 将前端应用程序以多路复用的方式映射到MySQL连接池以优化性能。 + - 查询结果重用 – 对于相同结果集的查询，多个查询并发查询时，vttablet会识别和管理相同查询，等待第一个查询结果完成，并发送给所有的调用者。 + - 事务管理 – 限制并发事务数、管理事务超时时间以优化总体吞吐量。 + +* 保护机制 + - 查询重写和清理 – 避免漫无目的的更新，对大查询添加limits。 + - 查询黑名单 – 可通过自定义规则以防止可能存在问题的查询命中数据库。 + - 查询超时 – 可自定义查询超时时间值，Vitess将干掉超时的查询。 + - 表别访问权限控制定义 – 可以针对不同的接入用户指定表的访问控制权限 (ACLs)。 + +* 监控 + - 性能分析: Vitess提供工具可让您监控，诊断和分析数据库性能。 + - 流式查询 – 使用传入查询列表来提供OLAP工作。 + - 更新流 – 服务器流式传输数据库中更改的行列表，可用作将更改传播到其他数据存储的机制。 + +* 拓扑管理工具 + - Master管理工具（用于reparent处理） + - 基于Web GUI的管理端 + - 可工作于多个数据中心/区域的设计 + +* 拆分 + - 几乎无缝的动态分片拆分 + - 支持垂直和水平分片拆分 + - 多种分片方案，支持自定义分片方案 + + +## 与其他数据库方案的比较 + +以下部分将Vitess与两种常见的替代方案进行比较，即vanilla MySQL实现和NoSQL实现。 + +### Vitess vs. Vanilla MySQL + +Vitess以几种方式改进了vanilla MySQL实现: + +| Vanilla MySQL | Vitess | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 每个MySQL连接的内存开销介于256KB和3MB之间，具体取决于您使用的MySQL版本。随着用户群的增长，您需要添加RAM以支持其他连接，但RAM不会有助于更快的查询。此外，获得连接时的CPU成本也很高。 | Vitess创建非常轻量级的连接。 Vitess的连接池功能使用Go语言的并发特性，将这些轻量级连接映射到一小部分MySQL连接中。因此，Vitess可以轻松处理数千个连接。 | +| 写的很烂的查询（例如未设置LIMIT的查询）会对拖慢数据库影响所有用户。 | Vitess实现了SQL解析器，并使用一组可配置的规则来重写可能会损害数据库性能的查询。 | +| 分片是对数据进行分区以提高可伸缩性和性能的手段。 MySQL本身不具备分片功能，要求您编写分片代码并在应用程序中嵌入分片逻辑。 | Vitess支持各种分片方案。它还可以将表迁移到不同的数据库中，并可以扩容或缩容扩展分片数。这些功能皆是非侵入式执行的，只需几秒钟的只读停机时间即可完成大多数数据转换。 | +| 使用复制实现高可用的MySQL集群具有主数据库和一些副本。如果主服务器出现故障，则副本应成为新主服务器。这要求您自己管理数据库生命周期并将当前系统状态传递给您的应用程序。 | Vitess有助于管理数据库方案的生命周期。它支持并自动处理各种方案，包括主故障迁移和数据备份。 | +| MySQL集群可以为不同的工作负载提供自定义数据库配置，例如用于写入的主数据库、用于Web客户端的快速只读副本、用于批处理作业的较慢只读副本等等。如果数据库具有水平分片，则需要为每个分片重复设置，并且应用需要在代码中加入逻辑以便找到正确的数据库。| Vitess使用分布式一致性键值存储拓扑服务，如etcd或ZooKeeper。这意味着群集元数据始终是最新的，并且对于不同的客户端是一致的。 Vitess还提供了一个代理，可以有效地将查询路由到最合适的MySQL实例。 + + +### Vitess vs. NoSQL + +如果您正在考虑NoSQL解决方案主要是因为担心MySQL的可扩展性，Vitess可能是您的应用程序更合适的选择。虽然NoSQL为非结构化数据提供了很好的支持，但Vitess仍然提供NoSQL数据存储所不具备的一些优势: + +| NoSQL | Vitess | +|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| NoSQL数据库没有传统数据库中库和表的概念，仅支持SQL语言的子集。 | Vitess不是简单的键值存储。它支持复杂的查询语义，例如where子句，JOINS，聚合函数等。 | +|NoSQL数据库不支持事务 | | +| NoSQL解决方案具有自定义API，可实现自定义结构，应用程序和工具。 | Vitess与MySQL之间仅有很小的差异，MySQL是一个大多数人已经习惯使用的数据库。 | +| NoSQL解决方案具有自定义API，可实现自定义结构，应用程序和工具。 | Vitess允许您使用MySQL的所有索引功能来优化查询性能。 | +| diff --git a/content/zh/docs/19.0/reference/_index.md b/content/zh/docs/19.0/reference/_index.md new file mode 100644 index 000000000..23d0931e1 --- /dev/null +++ b/content/zh/docs/19.0/reference/_index.md @@ -0,0 +1,9 @@ +--- +title: Reference +description: Detailed information about specific Vitess functionality +weight: 5 +--- + +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} \ No newline at end of file diff --git a/content/zh/docs/19.0/reference/messaging.md b/content/zh/docs/19.0/reference/messaging.md new file mode 100644 index 000000000..d0dc86136 --- /dev/null +++ b/content/zh/docs/19.0/reference/messaging.md @@ -0,0 +1,214 @@ +--- +title: Vitess Messaging +--- + +Vitess messaging gives the application an easy way to schedule and manage work +that needs to be performed asynchronously. Under the covers, messages are +stored in a traditional MySQL table and therefore enjoy the following +properties: + +* **Scalable**: Because of Vitess's sharding abilities, messages can scale to + very large QPS or sizes. +* **Guaranteed delivery**: A message will be indefinitely retried until a + successful ack is received. +* **Non-blocking**: If the sending is backlogged, new messages continue to be + accepted for eventual delivery. +* **Adaptive**: Messages that fail delivery are backed off exponentially with + jitter to prevent thundering herds. +* **Analytics**: Acknowledged messages are retained for a period of time — dictated + by the `time_acked` value for the row and the `vt_purge_after` (seconds) value + provided for the table — and can be used for analytics. +* **Transactional**: Messages can be created or acked as part of an existing + transaction. The action will complete only if the commit succeeds. + +The properties of a message are chosen by the application. However, every +message needs a uniquely identifiable key. If the messages are stored in a +sharded table, the key must also be the primary vindex of the table. + +Although messages will generally be delivered in the order they're created, +this is not an explicit guarantee of the system. The focus is more on keeping +track of the work that needs to be done and ensuring that it was performed. +Messages are good for: + +* Handing off work to another system. +* Recording potentially time-consuming work that needs to be done + asynchronously. +* Accumulating work that could be done during off-peak hours. + +Messages are not a good fit for the following use cases: + +* Broadcasting each event to multiple subscribers. +* Ordered delivery is required. +* Real-time delivery properties are required. + +## Creating a message table + +The current implementation requires a base fixed schema with properties defined +using Vitess specific table `COMMENT` directives. The message table format is as +follows: + +```sql +create table my_message( + # required columns + id bigint NOT NULL COMMENT 'often an event id, can also be auto-increment or a sequence', + priority tinyint NOT NULL DEFAULT '50' COMMENT 'lower number priorities process first', + epoch bigint NOT NULL DEFAULT '0' COMMENT 'Vitess increments this each time it sends the message, and is used for incremental backoff doubling', + time_next bigint DEFAULT 0 COMMENT 'the earliest time the message will be sent in epoch nanoseconds. Must be null if time_acked is set', + time_acked bigint DEFAULT NULL COMMENT 'the time the message was acked in epoch nanoseconds. Must be null if time_next is set', + + # add as many custom fields here as required + # optional - these are suggestions + tenant_id bigint COMMENT 'offers a nice way to segment your messages', + message json, + + # required indexes + primary key(id), + index poller_idx(time_acked, priority, time_next desc) + + # add any secondary indexes or foreign keys - no restrictions +) comment 'vitess_message,vt_min_backoff=30,vt_max_backoff=3600,vt_ack_wait=30,vt_purge_after=86400,vt_batch_size=10,vt_cache_size=10000,vt_poller_interval=30' +``` + +The application-related columns are as follows: + +* `id`: can be any type. Must be unique (for sharded message tables, this will typically be your primary vindex column). +* `message`: can be any type. +* `priority`: messages with a lower priority will be processed first. + +The noted indexes are recommended for optimum performance. However, some +variation can be allowed to achieve different performance trade-offs. + +The comment section specifies additional configuration parameters. The fields +are as follows: + +* `vitess_message`: Indicates that this is a message table. +* `vt_min_backoff=30`: Set lower bound, in seconds, on exponential backoff for + message retries. If not set, defaults to `vt_ack_wait` _(optional)_ +* `vt_max_backoff=3600`: Set upper bound, in seconds, on exponential backoff for + message retries. The default value is infinite backoff _(optional)_ +* `vt_ack_wait=30`: Wait for 30 seconds for the *first* message send to be acked. + If one is not received within this time frame, the message will be resent. +* `vt_purge_after=86400`: Purge acked messages that are older than 86400 + seconds (1 day). +* `vt_batch_size=10`: Send up to 10 messages per gRPC packet. +* `vt_cache_size=10000`: Store up to 10,000 messages in the cache. If the demand + is higher, the rest of the items will have to wait for the next poller cycle. +* `vt_poller_interval=30`: Poll every 30 seconds for messages that should be + [re]sent. + +If any of the above fields not marked as optional are missing, Vitess will fail to load the table. No +operation will be allowed on a table that has failed to load. + +## Enqueuing messages + +The application can enqueue messages using a standard `INSERT` statement, for example: + +```sql +insert into my_message(id, message) values(1, '{"message": "hello world"}') +``` + +These inserts can be part of a regular transaction. Multiple messages can be +inserted into different tables. Avoid accumulating too many big messages within a +transaction as it consumes memory on the VTTablet side. At the time of commit, +memory permitting, all messages are instantly enqueued to be sent. + +Messages can also be created to be sent in the future: + + ```sql + insert into my_message(id, message, time_next) values(1, '{"message": "hello world"}', :future_time) + ``` + + `future_time` must be a unix timestamp expressed in nanoseconds. + +## Receiving messages + +Processes can subscribe to receive messages by sending a `MessageStream` +gRPC request to a `VTGate` or using the `stream * from ` SQL statement +(if using the interactive mysql command-line client you must also pass the +`-q`/`--quick` option). If there are multiple subscribers, the messages will be +delivered in a round-robin fashion. Note that *this is not a broadcast*; each +message will be sent to at most one subscriber. + +The format for messages is the same as a standard Vitess `Result` received from +a `VTGate`. This means that standard database tools that understand query results +can also be message receivers. + +### Subsetting + +It's possible that you may want to subscribe to specific shards or groups of +shards while requesting messages. This is useful for partitioning or load +balancing. The `MessageStream` gRPC API call allows you to specify these +constraints. The request parameters are as follows: + +* `Name`: Name of the message table. +* `Keyspace`: Keyspace where the message table is present. +* `Shard`: For unsharded keyspaces, this is usually "0". However, an empty + shard will also work. For sharded keyspaces, a specific shard name can be + specified. +* `KeyRange`: If the keyspace is sharded, streaming will be performed only from + the shards that match the range. This must be an exact match. + +## Acknowledging messages + +A received and processed (you've completed some meaningful work based on the +message contents received) message can be acknowledged using the `MessageAck` +gRPC API call. This call accepts the following parameters: + +* `Name`: Name of the message table. +* `Keyspace`: Keyspace where the message table is present. This field can be + empty if the table name is unique across all keyspaces. +* `Ids`: The list of ids that need to be acked. + +Once a message is successfully acked, it will never be resent. + +## Exponential backoff + +For a message that was successfully sent we will wait for the specified `vt_ack_wait` +time. If no ack is received by then, it will be resent. The next attempt will be 2x +the previous wait and this delay is doubled for every subsequent attempt — bound by +`vt_min_backoff` and `vt_max_backoff` — with some added jitter (up to 33%) to avoid +thundering herds. + +## Purging + +Messages that have been successfully acked will be deleted after their age +exceeds the time period specified by `vt_purge_after`. + +## Advanced usage + +The `MessageAck` functionality is currently a gRPC API call and cannot be used +from the SQL interface. However, you can manually ack messages using a regular +DML query like this: + +```sql +update my_message set time_acked = :time_acked, time_next = null where id in ::ids and time_acked is null +``` + +You can also manually change the schedule of existing messages with a statement like +this: + +```sql +update my_message set priority = :priority, time_next = :time_next, epoch = :epoch where id in ::ids and time_acked is null +``` + +This comes in handy if a bunch of messages had chronic failures and got +postponed to the distant future. If the root cause of the problem was fixed, +the application could reschedule them to be delivered as soon as possible. You can +also optionally change the priority and or epoch. Lower priority and epoch values +both increase the relative priority of the message and the back-off is less +aggressive. + +You can also view messages using regular `SELECT` queries against the message table. + +## Known limitations + +Here is a short list of possible limitations/improvements: + +* Proactive scheduling: Upcoming messages can be proactively scheduled for + timely delivery instead of waiting for the next polling cycle. +* Changed properties: Although the engine detects new message tables, it does + not refresh the properties (such as `vt_ack_wait`) of an existing table. +* No explicit rate limiting. +* Usage of MySQL partitioning for more efficient purging. + + diff --git a/content/zh/docs/19.0/reference/mysql-server-protocol.md b/content/zh/docs/19.0/reference/mysql-server-protocol.md new file mode 100644 index 000000000..726cf4da1 --- /dev/null +++ b/content/zh/docs/19.0/reference/mysql-server-protocol.md @@ -0,0 +1,23 @@ +--- +title: MySQL Binary Protocol +weight: 4 +--- +Vitess supports MySQL binary protocol. This allows existing applications to connect to Vitess directly without any change, or without using a new driver or connector. This is now the recommended and the most popular protocol for connecting to Vitess. + +## Features of RPC protocol not supported by SQL protocol + +### Bind Variables + +The RPC protocol supports bind variables which allows Vitess to cache query plans providing much better execution times. + +### Event Tokens + +The RPC protocols allows you to use event tokens to get the latest binlog position. These can be used for cache invalidation. + +### Update Stream + +Update stream allows you to subscribe to changing rows. + +### Query Multiplexing + +Ability to multiplex multiple request/responses on the same TCP connection. diff --git a/content/zh/docs/19.0/reference/row-based-replication.md b/content/zh/docs/19.0/reference/row-based-replication.md new file mode 100644 index 000000000..09b41812a --- /dev/null +++ b/content/zh/docs/19.0/reference/row-based-replication.md @@ -0,0 +1,92 @@ +--- +title: Row Based Replication +weight: 7 +--- + +Since Vitess 2.2, Vitess has supported Row Based Replication. This document explains how it affects various Vitess features. + +See the [Vitess and Replication document](../vitess-replication) for an introduction on various types of replication and how it affects Vitess. + +## MySQL Row Based Replication + +With Row Based replication, a more compact binary version of the rows affected are sent through the replication stream, instead of the SQL statements. The slaves then do not spend any time parsing the SQL, or performing any complex SQL operations (like where clauses). They can just apply the new rows directly. + +A few binlog events are used: + +* Table Map event: describes a table that is affected by the next events. Contains the database and table name, the number of columns, and the Type for each column. It does not contain the individual column names, nor the flags for each column (so it is impossible to differentiate signed vs unsigned integers for instance). +* Write Rows: equivalent of Insert. +* Update Rows: change the values of some rows. +* Delete Rows: delete the provided rows. + +The binlog-row-image option can be used to control which rows are used to identify the columns for the Update and Delete Rows events. The default setting for that option is to log all columns. + +## Vitess Use of MySQL Replication Stream + +Vitess uses the Replication Stream in a number of places. This part explains how we use RBR for these. + +**vttablet Replication Stream Watcher** + +This is enabled by the `watch_replication_stream` option, and is used by [Update Stream](../update-stream). It only cares about the GTIDs for the events, so it is unaffected by the use of RBR. + +*Note*: the current vttablet also reloads the schema when it sees a DDL in the stream. See below for more information on this. DDLs are however not represented in RBR, so this is an orthogonal issue. + +### Update Stream + +The current implementation uses comments in the original SQL (in SQR) to provide the primary key of the column that is being changed. + +We are changing this to also parse the RBR events, and extract the primary key value. + +*Note*: this means we need accurate schema information. See below. + +### Filtered Replication + +This is used during horizontal and vertical resharding, to keep source and destination shards up to date. + +We need to transform the RBR events into SQL statements, filter them based either on keyspace_id (horizontal resharding) or table name (vertical resharding), and apply them. + +For horizontal splits, we need to understand the VSchema to be able to find the primary VIndex used for sharding. + +*Note*: this again means we need accurate schema information. We could do one of two things: + +* Send all statements to all destination shards, and let them do the filtering. They can have accurate schema information if they receive and apply all schema changes through Filtered Replication. +* Have the filtering be done on the stream server side, and assume the schema doesn't change in incompatible ways. As this is simpler for now, that's the option we're going with. + +## Database Schema Considerations + +### Interpreting RBR Events + +A lot of the work to interpret RBR events correctly requires knowledge of the table's schema. However, this introduces the possibility of inconsistencies during schema changes: the current schema for a table might be newer than the schema an older replication stream event was using. + +For the short term, Vitess will not deal very gracefully with this scenario: we will only support the case where the current schema for a table has exactly the same columns as all events in the binlog, plus some other optional columns that are then unused. That way, it is possible to add columns to tables without breaking anything. + +Note if the main use case is Filtered Replication for resharding, this limitation only exists while the resharding process is running. It is somewhat easy to not change the schema at the same time as resharding is on-going. + +### Applying Schema Changes + +When using RBR, [Schema Swap](../vitess-replication#vitess-schema-swap) becomes useless, as replication between hosts with different schemas will most likely break. This is however an existing limitation that is already known and handled by MySQL DBAs. + +Vitess at this point does not provide an integrated way of applying involved schema changes through RBR. A number of external tools however already exist to handle this case, like gh-ost. + +We have future plans to: + +* Integrate with a tool like gh-ost to provide a seamless schema change story. +* Maintain a history of the schema changes that happen on all shards, so events can be parsed correctly in all cases. + +## Unsupported Features + +This part describes the features that are not supported for RBR in Vitess as of December 2018: + +* *Floating point columns*: This is because they are inherently inaccurate, and could cause inaccuracies while being replayed during resharding. +* *Timezones support*: the binary logs store timestamps in UTC. When converting these to SQL, we print the UTC value. If the server is not in UTC, that will result in data corruption. Note: we are working on a fix for that one. + +## Update Stream Extensions + +[Update Stream](../update-stream) can be changed to contain both old and new values of the rows being changed. Again the values will depend on the schema. We will also make this feature optional, so if the client is using this for Primary Key based cache invalidation for instance, no extra unneeded data is sent. + +This can be used to re-populate a cache with Update Stream, instead of invalidating it, by putting the new values directly in there. + +Then, using this in conjunction with binlog-row-image would help provide a feature-complete way of always getting all changes on rows. It would also help handle Update Stream corner cases that replay events during resharding, when switching traffic from old to new shards. + +## Vttablet Simplifications + +A lot of the work done by vttablet now is to find the Primary Key of the modified rows, to rewrite the queries in an efficient way and tag each statement with the Primary Key. None of this may be necessary with RBR. diff --git a/content/zh/docs/19.0/reference/sharding.md b/content/zh/docs/19.0/reference/sharding.md new file mode 100644 index 000000000..eb8ff7d3a --- /dev/null +++ b/content/zh/docs/19.0/reference/sharding.md @@ -0,0 +1,108 @@ +--- +title: Sharding +description: Shard widely, shard often. +weight: 5 +--- + +Sharding is a method of horizontally partitioning a database to store data across two or more database servers. This document explains how sharding works in Vitess and the types of sharding that Vitess supports. + +## Overview + +A keyspace in Vitess can be sharded or unsharded. An unsharded keyspace maps directly to a MySQL database. If sharded, the rows of the keyspace are partitioned into different databases of identical schema. + +For example, if an application's "user" keyspace is split into two shards, each shard contains records for approximately half of the application's users. Similarly, each user's information is stored in only one shard. + +Note that sharding is orthogonal to (MySQL) replication. A Vitess shard typically contains one MySQL master and many MySQL slaves. The master handles write operations, while slaves handle read-only traffic, batch processing operations, and other tasks. Each MySQL instance within the shard should have the same data, excepting some replication lag. + +### Supported Operations + +Vitess supports the following types of sharding operations: + +* **Horizontal sharding:** Splitting or merging shards in a sharded keyspace +* **Vertical sharding:** Moving tables from an unsharded keyspace to + a different keyspace. + +With these features, you can start with a single keyspace that contains all of your data (in multiple tables). As your database grows, you can move tables to different keyspaces (vertical split) and shard some or all of those keyspaces (horizontal split) without any real downtime for your application. + +## Sharding scheme + +Vitess allows you to choose the type of sharding scheme by the choice of your Primary Vindex for the tables of a shard. Once you have chosen the Primary Vindex, you can choose the partitions depending on how the resulting keyspace IDs are distributed. + +Vitess calculates the sharding key or keys for each query and then routes that query to the appropriate shards. For example, a query that updates information about a particular user might be directed to a single shard in the application's "user" keyspace. On the other hand, a query that retrieves information about several products might be directed to one or more shards in the application's "product" keyspace. + +### Key Ranges and Partitions + +Vitess uses key ranges to determine which shards should handle any particular query. + +* A **key range** is a series of consecutive keyspace ID values. It has starting and ending values. A key falls inside the range if it is equal to or greater than the start value and strictly less than the end value. +* A **partition** represents a set of key ranges that covers the entire space. + +When building the serving graph for a sharded keyspace, Vitess ensures that each shard is valid and that the shards collectively constitute a full partition. In each keyspace, one shard must have a key range with an empty start value and one shard, which could be the same shard, must have a key range with an empty end value. + +* An empty start value represents the lowest value, and all values are greater than it. +* An empty end value represents a value larger than the highest possible value, and all values are strictly lower than it. + +Vitess always converts sharding keys to a left-justified binary string for computing a shard. This left-justification makes the right-most zeroes insignificant and optional. Therefore, the value `0x80` is always the middle value for sharding keys. So, in a keyspace with two shards, sharding keys that have a binary value lower than 0x80 are assigned to one shard. Keys with a binary value equal to or higher than 0x80 are assigned to the other shard. + +Several sample key ranges are shown below: + +``` sh +Start=[], End=[]: Full Key Range +Start=[], End=[0x80]: Lower half of the Key Range. +Start=[0x80], End=[]: Upper half of the Key Range. +Start=[0x40], End=[0x80]: Second quarter of the Key Range. +Start=[0xFF00], End=[0xFF80]: Second to last 1/512th of the Key Range. +``` + +Two key ranges are consecutive if the end value of one range equals the start value of the other range. + +### Shard Names + +A shard's name identifies the start and end of the shard's key range, printed in hexadecimal and separated by a hyphen. For instance, if a shard's key range is the array of bytes beginning with [ 0x80 ] and ending, noninclusively, with [ 0xc0], then the shard's name is `80-c0`. + +Using this naming convention, the following four shards would be a valid full partition: + +* -40 +* 40-80 +* 80-c0 +* c0- + +Shards do not need to handle the same size portion of the key space. For example, the following five shards would also be a valid full partition, possibly with a highly uneven distribution of keys. + +* -80 +* 80-c0 +* c0-dc00 +* dc00-dc80 +* dc80- + +## Resharding + +Resharding describes the process of updating the sharding scheme for a keyspace and dynamically reorganizing data to match the new scheme. During resharding, Vitess copies, verifies, and keeps data up-to-date on new shards while the existing shards continue to serve live read and write traffic. When you're ready to switch over, the migration occurs with only a few seconds of read-only downtime. During that time, existing data can be read, but new data cannot be written. + +The table below lists the sharding (or resharding) processes that you would typically perform for different types of requirements: + +Requirement | Action +----------- | ------ +Uniformly increase read capacity | Add replicas or split shards +Uniformly increase write capacity | Split shards +Reclaim overprovisioned resources | Merge shards and/or keyspaces +Increase geo-diversity | Add new cells and replicas +Cool a hot tablet | For read access, add replicas or split shards. For write access, split shards. + +### Filtered Replication + +The cornerstone of resharding is replicating the right data. Vitess implements the following functions to support filtered replication, the process that ensures that the correct source tablet data is transferred to the proper destination tablets. + +1. The server process uses the primary vindex to compute the keyspace ID for every row coming through the replication stream, and sends that row to the corresponding target shard. +2. The target shard converts the row into the corresponding DML (Data Manipulation Language) and applies the statement. + +If using RBR, it's generally required that you have full image turned on. However, if your Primary Vindex is also part of the Primary key, it's not required, because every RBR event +will always contain the full primary key of its affected row. + +### Additional Tools and Processes + +Vitess provides the following tools to help manage range-based shards: + +* The [vtctl](../vtctl) command-line tool supports functions for managing keyspaces, shards, tablets, and more. +* Client APIs account for sharding operations. +* The [MapReduce framework](https://github.com/vitessio/vitess/tree/master/java/hadoop/src/main/java/io/vitess/hadoop) fully utilizes key ranges to read data as quickly as possible, concurrently from all shards and all replicas. diff --git a/content/zh/docs/19.0/reference/update-stream.md b/content/zh/docs/19.0/reference/update-stream.md new file mode 100644 index 000000000..469172d9e --- /dev/null +++ b/content/zh/docs/19.0/reference/update-stream.md @@ -0,0 +1,257 @@ +--- +title: Update Stream +weight: 6 +--- +Update Stream is a Vitess service that provides a change stream for any keyspace. The use cases for this service include: + +* Providing an *invalidation* stream, that an application can use to maintain a cache. +* Maintain an external copy of the data in another system, that is only updated when the data changes. +* Maintain a change record of all the transactions that have been applied to the data. + +A good understanding of [Vitess Replication](../vitess-replication) is required to understand this document better. We will go through the use cases in a bit more details, then introduce the EventToken notion, and finally explain the service. + +## Use Cases + +### Maintaining Cache Consistency + +The first use case we’re trying to address is to maintain a consistent cache of the data. The problem here has two parts: + +* When data changes, we need to invalidate the cache. +* When we want to re-populate the cache after an invalidation, we need to make sure we get data that is more recent than the data change. For instance, we can’t just re-query any replica, as it might be behind on replication. + +This process can be somewhat resilient to some stream anomalies. For instance, invalidating the same record twice in some corner cases is fine, as long as we don’t poison the cache with an old value. + +Note the location / ownership of the cache is not set in stone: + +* Application-layer cache: the app servers maintain the cache. It’s very early in the serving chain, so in case of a cache hit, it’s lower latency. However, an invalidation process needs to run and is probably also owned by the application layer, which is somewhat annoying. +* vtgate-layer cache: it would be a row cache accessed by vtgate, transparent to the app. It requires vtgate to do a lot of extra heavy-lifting, depending on what we want to support. Cache invalidation is still required, at a row level. +* vttablet-layer cache: this is the old rowcache. Since the cache is not shared across instances, and the app still needs a cache, we abandoned this one. + +Since the vtgate-layer cache is much harder to work on (because of the query implications), and will probably require similar components as the app-layer cache, we decided to work on the app-layer cache for now, with possibly an invalidation process that is somewhat tied to the app. + +The *composite object cache* is an interesting use case: if the application is in charge of the cache, it would seem possible to put in the cache higher level composite objects, that are built from multiple table records. They would be invalidated any time one of the composing table record is changed. They need to be addressed by a part of the primary key, so they’re easy to find. + +### Change Log + +A Change Log provides a stream of all data changes, so an external application can either record these changes, or keep an external database up to date with the latest data. + +Unlike the Cache Invalidation use case, this is not as forgiving. If we have duplicate updates, they will need to be handled. + +## Design Considerations + +### Single Shard Update Stream + +This has been supported in Vitess for a while, but not exposed. It works as follows: + +* vttablet adds an SQL comment to every DML, that contains the Primary Key of the modified row. +* vttablet provides a streaming service that can connect to the local MySQL replication stream, extract the comment, and stream events to the client. +* Use the GTID as the start / restart position. It is sent back with each update, and an Update Stream can be started from it. + +Note Vitess supports both the MariaDB GTIDs (domain:server:sequence) and the MySQL 5.6 GTID Sets (encoded in SID blocks). + +### Surviving Resharding: Problem + +The Vitess tools are supposed to provide transparent sharding for the user’s data. Most of the trouble we run into is surviving resharding events, when we hop over from one set of shards to another set of shards. + +Two strategies then come to mind: + +* Provide a per-shard update stream. Let the user handle the hop when resharding happens. If we were to do this for the Cache use case, we would also need to provide some way of preventing bad corner cases, like a full cache flush, or no cache update for a while, or lost cache invalidations. Simple for us, but the app can be a lot more complicated. And the Change Log use case is also hard to do. +* Provide a per-keyrange update stream. Vtgate would connect to the right shards, and resolve all conflicts. We can add the restriction that the client only asks for keyranges that are exactly matching to one or more shards. For instance, if a keyspace is sharded four ways, -40, 40-80, 80-c0, c0-, we can support clients asking for -40, -80, -, but not for 60-a0 for instance. + +As a reminder, the resharding process is somewhat simple: + +* Let’s say we want to split a shard 20-40 into two shards, 20-30 and 30-40. At first, only 20-40 exists and has a GTID stream. +* We create 20-30 and 30-40, each has its own GTID stream. We copy the schema, and the data. +* Filtered replication is enabled. A transaction in 20-40 is replayed on both 20-30 and 30-40, with an extra blp_checkpoint statement, that saves the 20-40 GTID. +* At some point, we migrate the read-only traffic from 20-40 replicas to 20-30 and 30-40 replicas. (Note: this is probably when we want to migrate any invalidation process as well). +* Then as a final step, the writes are migrated from 20-40 to 20-30 and 30-40. + +So we have a window of time when both streams are available simultaneously. For the resharding process to be operationally better, that window should be as small as possible (so we don't run with two copies of the data for too long). So we will make sure an Update Stream can hop from the source shards to the destination shards quickly. + +### Surviving Resharding: First Try + +To solve the shard hop problem during resharding, we tried to explore adding good timing information to the replication stream. However: + +* Since the time is added by vttablet, not MySQL, it is not accurate, not monotonic, and provides no guarantees. +* Which such loose guarantees, it is no better than the second-accurate timestamp added by MySQL to each transaction. + +So this idea was abandoned. + +The GTID stream maintained by MySQL is the only true source of IDs for changes. It’s the only one we can trivially seek on, and get binlogs. The main issue with it is that it’s not maintained across shards when resharding. + +However, it is worth noting that a transaction replicated by the binlog streamer using Filtered Replication also saves the original GTID and the source transaction timestamp in the blp_checkpoint table. So we could extract the original GTID and timestamp from at least that statement (and if not, from an added comment). + +### Change Log and SBR + +If all we have is Statement Based Replication (SBR), we cannot get an accurate Change Log. SBR only provides the SQL statements, there is no easy way for us to parse them to get the final values of the columns (OK, there is, it’s just too complicated). And we cannot just query MySQL, as it may have already applied more transactions related to that record. So for Change Log, we need Row Based Replication (or a more advanced replication system). + +Note we can use the following setup: + +* Master and replicas use SBR. +* Rdonly use SBR to connect to master, but log RBR logs locally. +* We get the replication stream from rdonly servers. + +This is a bit awkward, and the main question is: what happens if a rdonly server is the only server that has replicated and semi-sync-acked a transaction, while the master is dying? Then to get that change, the other servers would get the RBR version of the change. + +Vitess support for RBR is coming. We will then explore these use cases further. + +## Detailed Design + +In the rest of this document, we’ll explore using the GTID when tracking a single shard, and revert to the timestamp when we hop across shards. + +As we do not want the application layer to understand / parse / compare the GTIDs, we’ll use an opaque token, and just pass it around the various layers. Vtgate / vttablet will understand it. The invalidation process should not have to, but will as there is no better solution. + +This approach can be made to work for the cache invalidation use case, but it might be difficult to provide an exact point in time for recovery / switching over to a different set of shards during resharding. + +For the Change Log, we’ll see what we can provide. + +### Event Token + +We define an Event Token structure that contains: + +* a MySQL replication timestamp (int64, seconds since Epoch). +* a shard name +* A GTIDSet position. + +It basically describes a position in a replication stream. + +An Event Token is always constructed from reading a transaction from the binlogs. If filtered replication is running, we use the source shard timestamp. + +Event Token comparison: + +* First, if the timestamps are different, just use that. +* Then, if both use the same shard name, compare the GTIDs. +* Otherwise we do not know for sure. It will depend on the usage to figure out what we do. + +*Possible Extension*: when filtered replication is running, we also update blp_checkpoint with the source GTID. We could add that information to the Event Token. Let’s try to go without in the first version, to remain simple. More on this later in the ‘Data Dump, Keeping it up to Date’ section. + +### Vttablet Changes + +**Watching the Replication Stream** + +Replicas are changed to add a background routine that reads the binlogs (controlled by the `watch_replication_stream` flag). When a tablet’s type is set to replica, the routine starts. It stops when the tablet is not replica any more (goes to master, worker, …). + +The routine starts reading the binlog from the current position. It then remembers: + +* The Event Token of the last seen transaction. +* *Possible Optimization*: A map of the first time a timestamp is seen to the corresponding GTID position and filename / position. This would be a value per second. Let’s age these out: we keep the values for the last N seconds, then we keep a value for every minute for the last M hours. We forget values older than 3 days (or whatever the binlog retention time is). + +**`include_event_token` Option** + +We added an option to the Query Service API for Execute calls, called `include_event_token`. If set, vttablet will get the last seen Event Token right before issuing the query to MySQL, and include it in the response. This essentially represents the last known replication position that we’re sure the data we’re returning is fresher than. + +**`compare_event_token` Option** + +We added an option to the Query Service API for Execute calls, called `compare_event_token`. The provided event token is sent along with the call, and vttablet compares that token with the one its current replication stream watcher has. It returns the result of the comparison in ResultExtras. + +**Update Stream API Change** + +The Update Stream API in vttablet right now can only start from a GTID. We added a new API that can start from a timestamp as well. It will look for the right binlog file to start with, and start streaming events, discarding events until it finds the provided timestamp. *Optimization*: It can also look in the map to find the closest value it can start with, and then read from the binlogs until it finds the first timestamp. If it doesn’t have old enough values in its map, it errors out (the goal is to have vtgate then try another tablet to start from). For each event, we will also return the corresponding Event Token. + +*Optimization*: if an Update Stream client is caught up to the current binlog reading thread, we can just tee the binlog stream to that client. We won’t do that in the first version, as we don’t expect that many clients. + +Note that when filtered replication is running, we need to have the timestamp of the source transaction on the source shard, not the local timestamp of the applied transaction. Which also means that timestamps will not be always linearly increasing in the stream, in the case of a shard merge (although they will be linearly increasing for a given keyspace_id). + +### Vtgate Changes + +We added a new Update Stream service to vtgate. It takes as input a keyspace and an optional KeyRange (for sharded keyspaces). As a starting point, it takes a timestamp. + +*Caveat*: As previously mentioned, at first, we can add the restriction that the client only asks for KeyRanges that are exactly matching to one or more shards. For instance, if a keyspace is sharded four ways, -40, 40-80, 80-c0, c0-, we can support clients asking for -40, -80, -, but not for 60-a0 for instance. Lifting that restriction is somewhat easy, we’d just have to filter the returned keyspace_ids by KeyRange, but that’s extra work for not much gain in the short term (and we don’t parse keyspace_id in Binlog Streamer right now, just the PK). + +After using the partition map in SrvKeyspace, vtgate will have a list of shards to query. It will need to create a connection for every shard that overlaps with the input KeyRange. For every shard, it will pick an up-to-date replica and use the Update Stream API mentioned above. If the vttablet cannot provide the stream, it will failover to another one. It will then start an Update Stream on all sources, and just merge and stream the results back to the source. For each Event Token that is read from a source, vtgate will also send the smallest timestamp of all Events it’s seen in all sources. That way the client has a value to start back from in case it needs to restart. + +In case of resharding event, the list of shards to connect to may change. Vtgate will build a map of overlapping shards, to know which source shards are mapped to which destination shards. It will then stop reading from all the source shards, find the minimum timestamp of the last event it got from each source, and use that to restart the stream on the destination shards. + +*Alternate Simpler Solution*: when vtgate notices a SrvKeyspace change in the serving shards, it just aborts the invalidation stream. The client is responsible for reconnecting with the last timestamp it’s seen. The client will need to handle this error case anyway (when vtgates get upgraded at least). + +Caveat: this will produce duplicate Event Tokens, with the same timestamp but with GTID positions from two different streams. More on this later, but for a Cache Invalidation scenario, no issue, and for a Change Log application, we’ll see how we can deal with it. + +We also add the same include_event_token flag to vtgate query service. It just passes it along to the underlying vttablet. It’s only supported for single-keyspace_id queries. The resulting EventToken is just returned back as is. + +## Use Cases How To + +Let's revisit our use cases and see how this addresses them. + +### Cache Invalidation + +The idea is to use the Event Token coming from both the Execute results and the Update Stream to maintain cache consistency. + +The cache contains entries with both: + +* An Event Token. It describes either the invalidation, or the last population. +* An optional value. + +The invalidation process works as follows: + +* It asks vtgate for an Update Stream for a provided keyspace / KeyRange, starting at the current timestamp (or from a few seconds/minutes/hours in the past, or from the last checkpointed timestamp it had saved). +* Vtgate resolves the keyrange into shards. It starts an invalidation stream with a healthy replica in each shard from the provided timestamp. +* Vtgate sends back all Event Tokens it collects, with all of timestamp, shard name and GTID. +* For each change it gets, the invalidation process reads the cache record. Two cases: + * No entry in the cache: it stores the Event Token (to indicate the cache should not be populated unless the value is greater) with no value. + * An entry in the cache exists, with an Event Token: + * If the cached Event Token is strictly older, update it with the new Event Token, clear the value. + * If the cached Event Token is strictly more recent, discard the new Event. + * If we don’t know which Event Token is the most recent (meaning they have the same timestamp, and are read from different invalidation stream), we need to do the safest thing: invalidate the cache with the current Event Token. This is the safest because we’re guaranteed to get duplicate events, and not miss events. + * In any case the invalidation process only updates the cache if it still contains the value it read (CAS). Otherwise it rereads and tries again (means an appserver or another invalidator somehow also updated the cache). + +A regular appserver will query the cache for the value it wants. It will get either: + +* No entry: asks vtgate for the Event Token when querying the database, use a CAS operation to set the value the returned Event Token + Value. +* An entry with both an Event Token and a Value: Just use the value. +* An entry with just an Event Token and no Value: +* Send the Event Token along with the query to vtgate as compare_event_token, and also asking for Event Token using include_event_token. +* Vtgate will query vttablet as usual, but also passing both flags. +* Vttablet will then compare the provided Event Token with the one that was included. It will include in the response the knowledge of the Event Token comparison as a boolean, only set if the data read is fresher. +* Depending on the fresher boolean flag, the app will: +* Data read is more recent: Update the cache with new Event Token / Value. +* Data read is not more recent (or we don't know for sure): don’t update the cache. + +*Constraints*: + +* When restarting the invalidation process, we start from a point back in time, let’s say N seconds behind now. Since we can ask destination shards at this point for events that are N seconds old, filtered replication has to have been running for at least N seconds. (Alternatively, the invalidators can checkpoint their current position from time to time, and restart from that when starting up, and revert back to N seconds behind now). +* As mentioned before, the shard range queried by the invalidation process should cover a round number of actual shards. +* The invalidation process needs to know how to compare tokens. This is a bummer, I don’t see any way around it. We could simplify and only do the timestamp comparison part, but that would mean the cache is unused for up to an entire second upon changes. The appserver doesn’t need to compare, it gives the value to vtgate and let it do the work. + +To see a sample use of the Update Stream feature, look at the cache_invalidation.py integration test. It shows how to do the invalidation in python, and the application component. + +### Extension: Removing Duplicate Events + +In the previous section, we use timestamps to easily seek on replication streams. If we added the ability to seek on any source GTID that appears in the destination stream, we should be able to precisely seek at the right spot. That would make exact transitions from one stream to the next possible. Again, as long as the destination shard in a resharding event has been running filtered replication for as long as we want to go back. + +However, describing a position on a replication stream becomes tricky: it needs one Event Token per replication stream. When resharding the Event Tokens would jump around. When restarting a stream from an Event Token list, we may need to restart earlier in some cases and skip some items. + +*Bottom Line*: + +* This would require a bunch of non-trivial code. +* This requires that filtered replication would be running for at least as long as we want to go back in time for the starting point. + +If there is no use case for it, let’s not do it. + +### Extension: Adding Update Data to the Stream, Towards Change Log + +Let’s add a flag to the streaming query, that, if specified, asks for the changed columns as well as the PK. + +* If using SBR, and the flag is present, vttablet can just query the row at the time we get the event, and send it along. As already mentioned, the data may not be exactly up to date. It is however guaranteed to be newer than the Event Token, which might be good enough to put in a cache for instance. +* If using RBR, we just get th* ata for free, just send it along. + +*Bottom Line*: Let’s try to go without this extension and see how it goes. We can implement the additional data when we fully support RBR. + +### Extension: Data Dump, Keeping It Up To Date + +*Use Case*: keep a secondary database (like a HBase database) up to date. Requirements: RBR replication, plus Data included in the Stream (previous extension). + +It’s simple: + +* The external database has the same schema as MySQL. Each row is indexed by PK. It also has an extra field, for the last Event Token. +* Remember start time of the process, let’s call it StartTime +* Dump the data to other database. Using Map/Reduce, whatever. Do not populate the Event Tokens. +* Start an invalidation process, asking for changes from StartTime. When getting updates, read the current external database row and its Event Token: + * If there is no existing row / no Event token, save the new value. + * If there is an existing row with a strictly more recent Event Token, ignore the event. + * Otherwise (when the existing Event Token is older or we don’t know), store the new Value / Event Token. + +Note this again means the dumping process needs to be able to compare Event Tokens, as the invalidator does. + +*Caveat*: As described, the values in the secondary storage will converge, but they may go back in time for a bit, as we will process duplicate events during resharding, and we may not know how to compare them. + +*Extension*: if we also add the source GTID in Event Tokens read from a destination shard during filtered replication, we can break the tie easily on duplicate events, and guarantee we only move forward. This seems like the easiest solution, and we can then use only timestamps as starting times for restarting the sync process. diff --git a/content/zh/docs/19.0/reference/vitess-api.md b/content/zh/docs/19.0/reference/vitess-api.md new file mode 100644 index 000000000..d480a0520 --- /dev/null +++ b/content/zh/docs/19.0/reference/vitess-api.md @@ -0,0 +1,1037 @@ +--- +title: Vitess API Reference +noToc: true +weight: 1 +--- + +This document describes Vitess API methods that enable your client application to more easily talk to your storage system to query data. API methods are grouped into the following categories: + +* [Range-based Sharding](#range-based-sharding) +* [Transactions](#transactions) +* [Custom Sharding](#custom-sharding) +* [Map Reduce](#map-reduce) +* [Topology](#topology) +* [v3 API (alpha)](#v3-api-(alpha)) + +The following table lists the methods in each group and links to more detail about each method: + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Range-based Sharding
    ExecuteBatchKeyspaceIdsExecuteBatchKeyspaceIds executes the list of queries based on the specified keyspace ids.
    ExecuteEntityIdsExecuteEntityIds executes the query based on the specified external id to keyspace id map.
    ExecuteKeyRangesExecuteKeyRanges executes the query based on the specified key ranges.
    ExecuteKeyspaceIdsExecuteKeyspaceIds executes the query based on the specified keyspace ids.
    StreamExecuteKeyRangesStreamExecuteKeyRanges executes a streaming query based on key ranges. Use this method if the query returns a large number of rows.
    StreamExecuteKeyspaceIdsStreamExecuteKeyspaceIds executes a streaming query based on keyspace ids. Use this method if the query returns a large number of rows.
    Transactions
    BeginBegin a transaction.
    CommitCommit a transaction.
    ResolveTransactionResolveTransaction resolves a transaction.
    RollbackRollback a transaction.
    Custom Sharding
    ExecuteBatchShardsExecuteBatchShards executes the list of queries on the specified shards.
    ExecuteShardsExecuteShards executes the query on the specified shards.
    StreamExecuteShardsStreamExecuteShards executes a streaming query based on shards. Use this method if the query returns a large number of rows.
    Map Reduce
    SplitQuerySplit a query into non-overlapping sub queries
    Topology
    GetSrvKeyspaceGetSrvKeyspace returns a SrvKeyspace object (as seen by this vtgate). This method is provided as a convenient way for clients to take a look at the sharding configuration for a Keyspace. Looking at the sharding information should not be used for routing queries (as the information may change, use the Execute calls for that). It is convenient for monitoring applications for instance, or if using custom sharding.
    v3 API (alpha)
    ExecuteExecute tries to route the query to the right shard. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query.
    StreamExecuteStreamExecute executes a streaming query based on shards. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query. Use this method if the query returns a large number of rows.
    +##Range-based Sharding +### ExecuteBatchKeyspaceIds + +ExecuteBatchKeyspaceIds executes the list of queries based on the specified keyspace ids. + +#### Request + + ExecuteBatchKeyspaceIdsRequest is the payload to ExecuteBatchKeyspaceId. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| queries
    list <[BoundKeyspaceIdQuery](#boundkeyspaceidquery)>| BoundKeyspaceIdQuery represents a single query request for the specified list of keyspace ids. This is used in a list for ExecuteBatchKeyspaceIdsRequest. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| as_transaction
    bool| as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose. (this can be seen as adding a 'begin' before and 'commit' after the queries). Only makes sense if tablet_type is master. If set, the Session is ignored. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + ExecuteBatchKeyspaceIdsResponse is the returned value from ExecuteBatchKeyspaceId. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| results
    list <[query.QueryResult](#query.queryresult)>| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### ExecuteEntityIds + +ExecuteEntityIds executes the query based on the specified external id to keyspace id map. + +#### Request + + ExecuteEntityIdsRequest is the payload to ExecuteEntityIds. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| entity_column_name
    string| entity_column_name is the column name to use. | +| entity_keyspace_ids
    list <[EntityId](#executeentityidsrequest.entityid)>| entity_keyspace_ids are pairs of entity_column_name values associated with its corresponding keyspace_id. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| not_in_transaction
    bool| not_in_transaction is deprecated and should not be used. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Messages + +##### ExecuteEntityIdsRequest.EntityId + +Properties + +| Name |Description | +| :-------- | :-------- +| type
    [query.Type](#query.type)| Type defines the various supported data types in bind vars and query results. | +| value
    bytes| value is the value for the entity. Not set if type is NULL_TYPE. | +| keyspace_id
    bytes| keyspace_id is the associated keyspace_id for the entity. | + +#### Response + + ExecuteEntityIdsResponse is the returned value from ExecuteEntityIds. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### ExecuteKeyRanges + +ExecuteKeyRanges executes the query based on the specified key ranges. + +#### Request + + ExecuteKeyRangesRequest is the payload to ExecuteKeyRanges. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to | +| key_ranges
    list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| not_in_transaction
    bool| not_in_transaction is deprecated and should not be used. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + ExecuteKeyRangesResponse is the returned value from ExecuteKeyRanges. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### ExecuteKeyspaceIds + +ExecuteKeyspaceIds executes the query based on the specified keyspace ids. + +#### Request + + ExecuteKeyspaceIdsRequest is the payload to ExecuteKeyspaceIds. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| keyspace_ids
    list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| not_in_transaction
    bool| not_in_transaction is deprecated and should not be used. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + ExecuteKeyspaceIdsResponse is the returned value from ExecuteKeyspaceIds. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### StreamExecuteKeyRanges + +StreamExecuteKeyRanges executes a streaming query based on key ranges. Use this method if the query returns a large number of rows. + +#### Request + + StreamExecuteKeyRangesRequest is the payload to StreamExecuteKeyRanges. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| key_ranges
    list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + StreamExecuteKeyRangesResponse is the returned value from StreamExecuteKeyRanges. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### StreamExecuteKeyspaceIds + +StreamExecuteKeyspaceIds executes a streaming query based on keyspace ids. Use this method if the query returns a large number of rows. + +#### Request + + StreamExecuteKeyspaceIdsRequest is the payload to StreamExecuteKeyspaceIds. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| keyspace_ids
    list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + StreamExecuteKeyspaceIdsResponse is the returned value from StreamExecuteKeyspaceIds. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +##Transactions +### Begin + +Begin a transaction. + +#### Request + + BeginRequest is the payload to Begin. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| single_db
    bool| single_db specifies if the transaction should be restricted to a single database. | + +#### Response + + BeginResponse is the returned value from Begin. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | + +### Commit + +Commit a transaction. + +#### Request + + CommitRequest is the payload to Commit. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| atomic
    bool| atomic specifies if the commit should go through the 2PC workflow to ensure atomicity. | + +#### Response + + CommitResponse is the returned value from Commit. + +##### Properties + +| Name |Description | +| :-------- | :-------- + +### ResolveTransaction + +ResolveTransaction resolves a transaction. + +#### Request + + ResolveTransactionRequest is the payload to ResolveTransaction. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| dtid
    string| dtid is the dtid of the transaction to be resolved. | + +#### Response + + ResolveTransactionResponse is the returned value from Rollback. + +##### Properties + +| Name |Description | +| :-------- | :-------- + +### Rollback + +Rollback a transaction. + +#### Request + + RollbackRequest is the payload to Rollback. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | + +#### Response + + RollbackResponse is the returned value from Rollback. + +##### Properties + +| Name |Description | +| :-------- | :-------- + +##Custom Sharding +### ExecuteBatchShards + +ExecuteBatchShards executes the list of queries on the specified shards. + +#### Request + + ExecuteBatchShardsRequest is the payload to ExecuteBatchShards + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| queries
    list <[BoundShardQuery](#boundshardquery)>| BoundShardQuery represents a single query request for the specified list of shards. This is used in a list for ExecuteBatchShardsRequest. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| as_transaction
    bool| as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose. (this can be seen as adding a 'begin' before and 'commit' after the queries). Only makes sense if tablet_type is master. If set, the Session is ignored. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + ExecuteBatchShardsResponse is the returned value from ExecuteBatchShards. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| results
    list <[query.QueryResult](#query.queryresult)>| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### ExecuteShards + +ExecuteShards executes the query on the specified shards. + +#### Request + + ExecuteShardsRequest is the payload to ExecuteShards. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| shards
    list <string>| shards to target the query to. A DML can only target one shard. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| not_in_transaction
    bool| not_in_transaction is deprecated and should not be used. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + ExecuteShardsResponse is the returned value from ExecuteShards. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### StreamExecuteShards + +StreamExecuteShards executes a streaming query based on shards. Use this method if the query returns a large number of rows. + +#### Request + + StreamExecuteShardsRequest is the payload to StreamExecuteShards. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| shards
    list <string>| shards to target the query to. | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + StreamExecuteShardsResponse is the returned value from StreamExecuteShards. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +##Map Reduce +### SplitQuery + +Split a query into non-overlapping sub queries + +#### Request + + SplitQueryRequest is the payload to SplitQuery. SplitQuery takes a "SELECT" query and generates a list of queries called "query-parts". Each query-part consists of the original query with an added WHERE clause that restricts the query-part to operate only on rows whose values in the the columns listed in the "split_column" field of the request (see below) are in a particular range. It is guaranteed that the set of rows obtained from executing each query-part on a database snapshot and merging (without deduping) the results is equal to the set of rows obtained from executing the original query on the same snapshot with the rows containing NULL values in any of the split_column's excluded. This is typically called by the MapReduce master when reading from Vitess. There it's desirable that the sets of rows returned by the query-parts have roughly the same size. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| keyspace
    string| keyspace to target the query to. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| split_column
    list <string>| Each generated query-part will be restricted to rows whose values in the columns listed in this field are in a particular range. The list of columns named here must be a prefix of the list of columns defining some index or primary key of the table referenced in 'query'. For many tables using the primary key columns (in order) is sufficient and this is the default if this field is omitted. See the comment on the 'algorithm' field for more restrictions and information. | +| split_count
    int64| You can specify either an estimate of the number of query-parts to generate or an estimate of the number of rows each query-part should return. Thus, exactly one of split_count or num_rows_per_query_part should be nonzero. The non-given parameter is calculated from the given parameter using the formula: split_count * num_rows_per_query_pary = table_size, where table_size is an approximation of the number of rows in the table. Note that if "split_count" is given it is regarded as an estimate. The number of query-parts returned may differ slightly (in particular, if it's not a whole multiple of the number of vitess shards). | +| num_rows_per_query_part
    int64| | +| algorithm
    query.SplitQueryRequest.Algorithm| The algorithm to use to split the query. The split algorithm is performed on each database shard in parallel. The lists of query-parts generated by the shards are merged and returned to the caller. Two algorithms are supported: EQUAL_SPLITS If this algorithm is selected then only the first 'split_column' given is used (or the first primary key column if the 'split_column' field is empty). In the rest of this algorithm's description, we refer to this column as "the split column". The split column must have numeric type (integral or floating point). The algorithm works by taking the interval [min, max], where min and max are the minimum and maximum values of the split column in the table-shard, respectively, and partitioning it into 'split_count' sub-intervals of equal size. The added WHERE clause of each query-part restricts that part to rows whose value in the split column belongs to a particular sub-interval. This is fast, but requires that the distribution of values of the split column be uniform in [min, max] for the number of rows returned by each query part to be roughly the same. FULL_SCAN If this algorithm is used then the split_column must be the primary key columns (in order). This algorithm performs a full-scan of the table-shard referenced in 'query' to get "boundary" rows that are num_rows_per_query_part apart when the table is ordered by the columns listed in 'split_column'. It then restricts each query-part to the rows located between two successive boundary rows. This algorithm supports multiple split_column's of any type, but is slower than EQUAL_SPLITS. | +| use_split_query_v2
    bool| Remove this field after this new server code is released to prod. We must keep it for now, so that clients can still send it to the old server code currently in production. | + +#### Response + + SplitQueryResponse is the returned value from SplitQuery. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| splits
    list <[Part](#splitqueryresponse.part)>| splits contains the queries to run to fetch the entire data set. | + +#### Messages + +##### SplitQueryResponse.KeyRangePart + +Properties + +| Name |Description | +| :-------- | :-------- +| keyspace
    string| keyspace to target the query to. | +| key_ranges
    list <[topodata.KeyRange](#topodata.keyrange)>| KeyRange describes a range of sharding keys, when range-based sharding is used. | + +##### SplitQueryResponse.Part + +Properties + +| Name |Description | +| :-------- | :-------- +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| key_range_part
    [KeyRangePart](#splitqueryresponse.keyrangepart)| key_range_part is set if the query should be executed by ExecuteKeyRanges. | +| shard_part
    [ShardPart](#splitqueryresponse.shardpart)| shard_part is set if the query should be executed by ExecuteShards. | +| size
    int64| size is the approximate number of rows this query will return. | + +##### SplitQueryResponse.ShardPart + +Properties + +| Name |Description | +| :-------- | :-------- +| keyspace
    string| keyspace to target the query to. | +| shards
    list <string>| shards to target the query to. | + +##Topology +### GetSrvKeyspace + +GetSrvKeyspace returns a SrvKeyspace object (as seen by this vtgate). This method is provided as a convenient way for clients to take a look at the sharding configuration for a Keyspace. Looking at the sharding information should not be used for routing queries (as the information may change, use the Execute calls for that). It is convenient for monitoring applications for instance, or if using custom sharding. + +#### Request + + GetSrvKeyspaceRequest is the payload to GetSrvKeyspace. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| keyspace
    string| keyspace name to fetch. | + +#### Response + + GetSrvKeyspaceResponse is the returned value from GetSrvKeyspace. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| srv_keyspace
    [topodata.SrvKeyspace](#topodata.srvkeyspace)| SrvKeyspace is a rollup node for the keyspace itself. | + +##v3 API (alpha) +### Execute + +Execute tries to route the query to the right shard. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query. + +#### Request + + ExecuteRequest is the payload to Execute. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| not_in_transaction
    bool| not_in_transaction is deprecated and should not be used. | +| keyspace
    string| keyspace to target the query to. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + ExecuteResponse is the returned value from Execute. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| session
    [Session](#session)| Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. | +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### StreamExecute + +StreamExecute executes a streaming query based on shards. It depends on the query and bind variables to provide enough information in conjonction with the vindexes to route the query. Use this method if the query returns a large number of rows. + +#### Request + + StreamExecuteRequest is the payload to StreamExecute. + +##### Parameters + +| Name |Description | +| :-------- | :-------- +| caller_id
    [vtrpc.CallerID](#vtrpc.callerid)| CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. | +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | +| keyspace
    string| keyspace to target the query to. | +| options
    [query.ExecuteOptions](#query.executeoptions)| ExecuteOptions is passed around for all Execute calls. | + +#### Response + + StreamExecuteResponse is the returned value from StreamExecute. + +##### Properties + +| Name |Description | +| :-------- | :-------- +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +## Enums + +### query.Type + + Type defines the various supported data types in bind vars and query results. + +| Name |Value |Description | +| :-------- | :-------- | :-------- +| NULL_TYPE | 0 | NULL_TYPE specifies a NULL type. | +| INT8 | 257 | INT8 specifies a TINYINT type. Properties: 1, IsNumber. | +| UINT8 | 770 | UINT8 specifies a TINYINT UNSIGNED type. Properties: 2, IsNumber, IsUnsigned. | +| INT16 | 259 | INT16 specifies a SMALLINT type. Properties: 3, IsNumber. | +| UINT16 | 772 | UINT16 specifies a SMALLINT UNSIGNED type. Properties: 4, IsNumber, IsUnsigned. | +| INT24 | 261 | INT24 specifies a MEDIUMINT type. Properties: 5, IsNumber. | +| UINT24 | 774 | UINT24 specifies a MEDIUMINT UNSIGNED type. Properties: 6, IsNumber, IsUnsigned. | +| INT32 | 263 | INT32 specifies a INTEGER type. Properties: 7, IsNumber. | +| UINT32 | 776 | UINT32 specifies a INTEGER UNSIGNED type. Properties: 8, IsNumber, IsUnsigned. | +| INT64 | 265 | INT64 specifies a BIGINT type. Properties: 9, IsNumber. | +| UINT64 | 778 | UINT64 specifies a BIGINT UNSIGNED type. Properties: 10, IsNumber, IsUnsigned. | +| FLOAT32 | 1035 | FLOAT32 specifies a FLOAT type. Properties: 11, IsFloat. | +| FLOAT64 | 1036 | FLOAT64 specifies a DOUBLE or REAL type. Properties: 12, IsFloat. | +| TIMESTAMP | 2061 | TIMESTAMP specifies a TIMESTAMP type. Properties: 13, IsQuoted. | +| DATE | 2062 | DATE specifies a DATE type. Properties: 14, IsQuoted. | +| TIME | 2063 | TIME specifies a TIME type. Properties: 15, IsQuoted. | +| DATETIME | 2064 | DATETIME specifies a DATETIME type. Properties: 16, IsQuoted. | +| YEAR | 785 | YEAR specifies a YEAR type. Properties: 17, IsNumber, IsUnsigned. | +| DECIMAL | 18 | DECIMAL specifies a DECIMAL or NUMERIC type. Properties: 18, None. | +| TEXT | 6163 | TEXT specifies a TEXT type. Properties: 19, IsQuoted, IsText. | +| BLOB | 10260 | BLOB specifies a BLOB type. Properties: 20, IsQuoted, IsBinary. | +| VARCHAR | 6165 | VARCHAR specifies a VARCHAR type. Properties: 21, IsQuoted, IsText. | +| VARBINARY | 10262 | VARBINARY specifies a VARBINARY type. Properties: 22, IsQuoted, IsBinary. | +| CHAR | 6167 | CHAR specifies a CHAR type. Properties: 23, IsQuoted, IsText. | +| BINARY | 10264 | BINARY specifies a BINARY type. Properties: 24, IsQuoted, IsBinary. | +| BIT | 2073 | BIT specifies a BIT type. Properties: 25, IsQuoted. | +| ENUM | 2074 | ENUM specifies an ENUM type. Properties: 26, IsQuoted. | +| SET | 2075 | SET specifies a SET type. Properties: 27, IsQuoted. | +| TUPLE | 28 | TUPLE specifies a a tuple. This cannot be returned in a QueryResult, but it can be sent as a bind var. Properties: 28, None. | +| GEOMETRY | 2077 | GEOMETRY specifies a GEOMETRY type. Properties: 29, IsQuoted. | +| JSON | 2078 | JSON specified a JSON type. Properties: 30, IsQuoted. | + +### topodata.KeyspaceIdType + + KeyspaceIdType describes the type of the sharding key for a range-based sharded keyspace. + +| Name |Value |Description | +| :-------- | :-------- | :-------- +| UNSET | 0 | UNSET is the default value, when range-based sharding is not used. | +| UINT64 | 1 | UINT64 is when uint64 value is used. This is represented as 'unsigned bigint' in mysql | +| BYTES | 2 | BYTES is when an array of bytes is used. This is represented as 'varbinary' in mysql | + +### topodata.TabletType + + TabletType represents the type of a given tablet. + +| Name |Value |Description | +| :-------- | :-------- | :-------- +| UNKNOWN | 0 | UNKNOWN is not a valid value. | +| MASTER | 1 | MASTER is the master server for the shard. Only MASTER allows DMLs. | +| REPLICA | 2 | REPLICA is a slave type. It is used to serve live traffic. A REPLICA can be promoted to MASTER. A demoted MASTER will go to REPLICA. | +| RDONLY | 3 | RDONLY (old name) / BATCH (new name) is used to serve traffic for long-running jobs. It is a separate type from REPLICA so long-running queries don't affect web-like traffic. | +| BATCH | 3 | | +| SPARE | 4 | SPARE is a type of servers that cannot serve queries, but is available in case an extra server is needed. | +| EXPERIMENTAL | 5 | EXPERIMENTAL is like SPARE, except it can serve queries. This type can be used for usages not planned by Vitess, like online export to another storage engine. | +| BACKUP | 6 | BACKUP is the type a server goes to when taking a backup. No queries can be served in BACKUP mode. | +| RESTORE | 7 | RESTORE is the type a server uses when restoring a backup, at startup time. No queries can be served in RESTORE mode. | +| DRAINED | 8 | DRAINED is the type a server goes into when used by Vitess tools to perform an offline action. It is a serving type (as the tools processes may need to run queries), but it's not used to route queries from Vitess users. In this state, this tablet is dedicated to the process that uses it. | + +### vtrpc.ErrorCode + + ErrorCode is the enum values for Errors. Internally, errors should be created with one of these codes. These will then be translated over the wire by various RPC frameworks. + +| Name |Value |Description | +| :-------- | :-------- | :-------- +| SUCCESS | 0 | SUCCESS is returned from a successful call. | +| CANCELLED | 1 | CANCELLED means that the context was cancelled (and noticed in the app layer, as opposed to the RPC layer). | +| UNKNOWN_ERROR | 2 | UNKNOWN_ERROR includes: 1. MySQL error codes that we don't explicitly handle. 2. MySQL response that wasn't as expected. For example, we might expect a MySQL timestamp to be returned in a particular way, but it wasn't. 3. Anything else that doesn't fall into a different bucket. | +| BAD_INPUT | 3 | BAD_INPUT is returned when an end-user either sends SQL that couldn't be parsed correctly, or tries a query that isn't supported by Vitess. | +| DEADLINE_EXCEEDED | 4 | DEADLINE_EXCEEDED is returned when an action is taking longer than a given timeout. | +| INTEGRITY_ERROR | 5 | INTEGRITY_ERROR is returned on integrity error from MySQL, usually due to duplicate primary keys. | +| PERMISSION_DENIED | 6 | PERMISSION_DENIED errors are returned when a user requests access to something that they don't have permissions for. | +| RESOURCE_EXHAUSTED | 7 | RESOURCE_EXHAUSTED is returned when a query exceeds its quota in some dimension and can't be completed due to that. Queries that return RESOURCE_EXHAUSTED should not be retried, as it could be detrimental to the server's health. Examples of errors that will cause the RESOURCE_EXHAUSTED code: 1. TxPoolFull: this is retried server-side, and is only returned as an error if the server-side retries failed. 2. Query is killed due to it taking too long. | +| QUERY_NOT_SERVED | 8 | QUERY_NOT_SERVED means that a query could not be served right now. Client can interpret it as: "the tablet that you sent this query to cannot serve the query right now, try a different tablet or try again later." This could be due to various reasons: QueryService is not serving, should not be serving, wrong shard, wrong tablet type, blacklisted table, etc. Clients that receive this error should usually retry the query, but after taking the appropriate steps to make sure that the query will get sent to the correct tablet. | +| NOT_IN_TX | 9 | NOT_IN_TX means that we're not currently in a transaction, but we should be. | +| INTERNAL_ERROR | 10 | INTERNAL_ERRORs are problems that only the server can fix, not the client. These errors are not due to a query itself, but rather due to the state of the system. Generally, we don't expect the errors to go away by themselves, but they may go away after human intervention. Examples of scenarios where INTERNAL_ERROR is returned: 1. Something is not configured correctly internally. 2. A necessary resource is not available, and we don't expect it to become available by itself. 3. A sanity check fails. 4. Some other internal error occurs. Clients should not retry immediately, as there is little chance of success. However, it's acceptable for retries to happen internally, for example to multiple backends, in case only a subset of backend are not functional. | +| TRANSIENT_ERROR | 11 | TRANSIENT_ERROR is used for when there is some error that we expect we can recover from automatically - often due to a resource limit temporarily being reached. Retrying this error, with an exponential backoff, should succeed. Clients should be able to successfully retry the query on the same backends. Examples of things that can trigger this error: 1. Query has been throttled 2. VtGate could have request backlog | +| UNAUTHENTICATED | 12 | UNAUTHENTICATED errors are returned when a user requests access to something, and we're unable to verify the user's authentication. | + +## Messages + +### BoundKeyspaceIdQuery + +BoundKeyspaceIdQuery represents a single query request for the specified list of keyspace ids. This is used in a list for ExecuteBatchKeyspaceIdsRequest. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| keyspace_ids
    list <bytes>| keyspace_ids contains the list of keyspace_ids affected by this query. Will be used to find the shards to send the query to. | + +### BoundShardQuery + +BoundShardQuery represents a single query request for the specified list of shards. This is used in a list for ExecuteBatchShardsRequest. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| query
    [query.BoundQuery](#query.boundquery)| BoundQuery is a query with its bind variables | +| keyspace
    string| keyspace to target the query to. | +| shards
    list <string>| shards to target the query to. A DML can only target one shard. | + +### Session + +Session objects are session cookies and are invalidated on use. Query results will contain updated session values. Their content should be opaque to the user. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| in_transaction
    bool| | +| shard_sessions
    list <[ShardSession](#session.shardsession)>| | +| single_db
    bool| single_db specifies if the transaction should be restricted to a single database. | + +#### Messages + +##### Session.ShardSession + +Properties + +| Name |Description | +| :-------- | :-------- +| target
    [query.Target](#query.target)| Target describes what the client expects the tablet is. If the tablet does not match, an error is returned. | +| transaction_id
    int64| | + +### query.BindVariable + +BindVariable represents a single bind variable in a Query. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| type
    [Type](#query.type)| | +| value
    bytes| | +| values
    list <[Value](#query.value)>| Value represents a typed value. | + +### query.BoundQuery + +BoundQuery is a query with its bind variables + +#### Properties + +| Name |Description | +| :-------- | :-------- +| sql
    string| sql is the SQL query to execute | +| bind_variables
    map <string, [BindVariable](#query.bindvariable)>| bind_variables is a map of all bind variables to expand in the query | + +### query.EventToken + +EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| timestamp
    int64| timestamp is the MySQL timestamp of the statements. Seconds since Epoch. | +| shard
    string| The shard name that applied the statements. Note this is not set when streaming from a vttablet. It is only used on the client -> vtgate link. | +| position
    string| The position on the replication stream after this statement was applied. It is not the transaction ID / GTID, but the position / GTIDSet. | + +### query.ExecuteOptions + +ExecuteOptions is passed around for all Execute calls. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| include_event_token
    bool| This used to be exclude_field_names, which was replaced by IncludedFields enum below If set, we will try to include an EventToken with the responses. | +| compare_event_token
    [EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. | +| included_fields
    [IncludedFields](#executeoptions.includedfields)| Controls what fields are returned in Field message responses from mysql, i.e. field name, table name, etc. This is an optimization for high-QPS queries where the client knows what it's getting | + +#### Enums + +##### ExecuteOptions.IncludedFields + +| Name |Value |Description | +| :-------- | :-------- | :-------- +| TYPE_AND_NAME | 0 | | +| TYPE_ONLY | 1 | | +| ALL | 2 | | + +### query.Field + +Field describes a single column returned by a query + +#### Properties + +| Name |Description | +| :-------- | :-------- +| name
    string| name of the field as returned by mysql C API | +| type
    [Type](#query.type)| vitess-defined type. Conversion function is in sqltypes package. | +| table
    string| Remaining fields from mysql C API. These fields are only populated when ExecuteOptions.included_fields is set to IncludedFields.ALL. | +| org_table
    string| | +| database
    string| | +| org_name
    string| | +| column_length
    uint32| column_length is really a uint32. All 32 bits can be used. | +| charset
    uint32| charset is actually a uint16. Only the lower 16 bits are used. | +| decimals
    uint32| decimals is actualy a uint8. Only the lower 8 bits are used. | +| flags
    uint32| flags is actually a uint16. Only the lower 16 bits are used. | + +### query.QueryResult + +QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). + +#### Properties + +| Name |Description | +| :-------- | :-------- +| fields
    list <[Field](#query.field)>| Field describes a single column returned by a query | +| rows_affected
    uint64| | +| insert_id
    uint64| | +| rows
    list <[Row](#query.row)>| Row is a database row. | +| extras
    [ResultExtras](#query.resultextras)| ResultExtras contains optional out-of-band information. Usually the extras are requested by adding ExecuteOptions flags. | + +### query.ResultExtras + +ResultExtras contains optional out-of-band information. Usually the extras are requested by adding ExecuteOptions flags. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| event_token
    [EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. | +| fresher
    bool| If set, it means the data returned with this result is fresher than the compare_token passed in the ExecuteOptions. | + +### query.ResultWithError + +ResultWithError represents a query response in the form of result or error but not both. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| error
    [vtrpc.RPCError](#vtrpc.rpcerror)| RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. | +| result
    [query.QueryResult](#query.queryresult)| QueryResult is returned by Execute and ExecuteStream. As returned by Execute, len(fields) is always equal to len(row) (for each row in rows). As returned by StreamExecute, the first QueryResult has the fields set, and subsequent QueryResult have rows set. And as Execute, len(QueryResult[0].fields) is always equal to len(row) (for each row in rows for each QueryResult in QueryResult[1:]). | + +### query.Row + +Row is a database row. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| lengths
    list <sint64>| lengths contains the length of each value in values. A length of -1 means that the field is NULL. While reading values, you have to accummulate the length to know the offset where the next value begins in values. | +| values
    bytes| values contains a concatenation of all values in the row. | + +### query.StreamEvent + +StreamEvent describes a set of transformations that happened as a single transactional unit on a server. It is streamed back by the Update Stream calls. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| statements
    list <[Statement](#streamevent.statement)>| The statements in this transaction. | +| event_token
    [EventToken](#query.eventtoken)| EventToken is a structure that describes a point in time in a replication stream on one shard. The most recent known replication position can be retrieved from vttablet when executing a query. It is also sent with the replication streams from the binlog service. | + +#### Messages + +##### StreamEvent.Statement + +One individual Statement in a transaction. + +Properties + +| Name |Description | +| :-------- | :-------- +| category
    [Category](#streamevent.statement.category)| | +| table_name
    string| table_name, primary_key_fields and primary_key_values are set for DML. | +| primary_key_fields
    list <[Field](#query.field)>| Field describes a single column returned by a query | +| primary_key_values
    list <[Row](#query.row)>| Row is a database row. | +| sql
    bytes| sql is set for all queries. FIXME(alainjobart) we may not need it for DMLs. | + +#### Enums + +##### StreamEvent.Statement.Category + + One individual Statement in a transaction. The category of one statement. + +| Name |Value |Description | +| :-------- | :-------- | :-------- +| Error | 0 | | +| DML | 1 | | +| DDL | 2 | | + +### query.Target + +Target describes what the client expects the tablet is. If the tablet does not match, an error is returned. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| keyspace
    string| | +| shard
    string| | +| tablet_type
    [topodata.TabletType](#topodata.tablettype)| TabletType represents the type of a given tablet. | + +### query.Value + +Value represents a typed value. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| type
    [Type](#query.type)| | +| value
    bytes| | + +### topodata.KeyRange + +KeyRange describes a range of sharding keys, when range-based sharding is used. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| start
    bytes| | +| end
    bytes| | + +### topodata.ShardReference + +ShardReference is used as a pointer from a SrvKeyspace to a Shard + +#### Properties + +| Name |Description | +| :-------- | :-------- +| name
    string| Copied from Shard. | +| key_range
    [KeyRange](#topodata.keyrange)| KeyRange describes a range of sharding keys, when range-based sharding is used. | + +### topodata.SrvKeyspace + +SrvKeyspace is a rollup node for the keyspace itself. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| partitions
    list <[KeyspacePartition](#srvkeyspace.keyspacepartition)>| The partitions this keyspace is serving, per tablet type. | +| sharding_column_name
    string| copied from Keyspace | +| sharding_column_type
    [KeyspaceIdType](#topodata.keyspaceidtype)| | +| served_from
    list <[ServedFrom](#srvkeyspace.servedfrom)>| | + +#### Messages + +##### SrvKeyspace.KeyspacePartition + +Properties + +| Name |Description | +| :-------- | :-------- +| served_type
    [TabletType](#topodata.tablettype)| The type this partition applies to. | +| shard_references
    list <[ShardReference](#topodata.shardreference)>| ShardReference is used as a pointer from a SrvKeyspace to a Shard | + +##### SrvKeyspace.ServedFrom + +ServedFrom indicates a relationship between a TabletType and the keyspace name that's serving it. + +Properties + +| Name |Description | +| :-------- | :-------- +| tablet_type
    [TabletType](#topodata.tablettype)| ServedFrom indicates a relationship between a TabletType and the keyspace name that's serving it. the tablet type | +| keyspace
    string| the keyspace name that's serving it | + +### vtrpc.CallerID + +CallerID is passed along RPCs to identify the originating client for a request. It is not meant to be secure, but only informational. The client can put whatever info they want in these fields, and they will be trusted by the servers. The fields will just be used for logging purposes, and to easily find a client. VtGate propagates it to VtTablet, and VtTablet may use this information for monitoring purposes, to display on dashboards, or for blacklisting purposes. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| principal
    string| principal is the effective user identifier. It is usually filled in with whoever made the request to the appserver, if the request came from an automated job or another system component. If the request comes directly from the Internet, or if the Vitess client takes action on its own accord, it is okay for this field to be absent. | +| component
    string| component describes the running process of the effective caller. It can for instance be the hostname:port of the servlet initiating the database call, or the container engine ID used by the servlet. | +| subcomponent
    string| subcomponent describes a component inside the immediate caller which is responsible for generating is request. Suggested values are a servlet name or an API endpoint name. | + +### vtrpc.RPCError + +RPCError is an application-level error structure returned by VtTablet (and passed along by VtGate if appropriate). We use this so the clients don't have to parse the error messages, but instead can depend on the value of the code. + +#### Properties + +| Name |Description | +| :-------- | :-------- +| code
    [ErrorCode](#vtrpc.errorcode)| | +| message
    string| | diff --git a/content/zh/docs/19.0/reference/vitess-replication.md b/content/zh/docs/19.0/reference/vitess-replication.md new file mode 100644 index 000000000..bcecec3ed --- /dev/null +++ b/content/zh/docs/19.0/reference/vitess-replication.md @@ -0,0 +1,87 @@ +--- +title: Vitess, MySQL Replication, and Schema Changes +weight: 5 +--- + +## Statement vs Row Based Replication + +MySQL supports two primary modes of replication in its binary logs: statement or row based. Vitess supports both these modes. + +For schema changes, if the number of affected rows is greater > 100k (configurable), we don't allow direct application of DDLs. The recommended tools in such cases are [gh-ost](https://github.com/github/gh-ost) or [pt-osc](https://www.percona.com/doc/percona-toolkit/LATEST/pt-online-schema-change.html). + +Not all statements are safe for Statement Based Replication (SBR): https://dev.mysql.com/doc/refman/8.0/en/replication-rbr-safe-unsafe.html. Vitess rewrites some of these statements to be safe for SBR, and others are explicitly failed. This is described in detail below. + +With statement based replication, it becomes easier to perform offline advanced schema changes, or large data updates. Vitess’s solution is called schema swap (described below). + +## Rewriting Update Statements + +Vitess rewrites ‘UPDATE’ SQL statements to always know what rows will be affected. For instance, this statement: + +``` sql +UPDATE SET WHERE +``` + +Will be rewritten into: + +``` sql +SELECT FROM
    WHERE FOR UPDATE +UPDATE
    SET WHERE IN /* primary key values: … */ +``` + +With this rewrite in effect, we know exactly which rows are affected, by primary key, and we also document them as a SQL comment. + +The replication stream then doesn’t contain the expensive WHERE clauses, but only the UPDATE statements by primary key. In a sense, it is combining the best of row based and statement based replication: the slaves only do primary key based updates, but the replication stream is very friendly for schema changes. + +Also, Vitess adds comments to the rewritten statements that identify the primary key affected by that statement. This allows us to produce an Update Stream (see section below). + +## Vitess Schema Swap + +Within YouTube, we also use a combination of statement based replication and backups to apply long-running schema changes without disrupting ongoing operations. See the [schema swap](../schema-management/schema-swap) tutorial for a detailed example. + +This operation, which is called **schema swap**, works as follows: + +* Pick a slave, take it out of service. It is not used by clients any more. +* Apply whatever schema or large data change is needed, on the slave. +* Take a backup of that slave. +* On all the other slaves, one at a time, take them out of service, restore the backup, catch up on replication, put them back into service. +* When all slaves are done, reparent to a slave that has applied the change. +* The old master can then be restored from a backup too, and put back into service. + +With this process, the only guarantee we need is for the change (schema or data) to be backward compatible: the clients won’t know if they talk to a server that has applied the change yet or not. This is usually fairly easy to deal with: + +* When adding a column, clients cannot use it until the schema swap is done. +* When removing a column, all clients must stop referring to it before the schema swap begins. +* A column rename is still tricky: the best way to do it is to add a new column with the new name in one schema swap, then change the client to populate both (and backfill the values), then change the client again to use the new column only, then use another schema swap to remove the original column. +* A whole bunch of operations are really easy to perform though: index changes, optimize table, … + +Note the real change is only applied to one instance. We then rely on the backup / restore process to propagate the change. This is a very good improvement from letting the changes through the replication stream, where they are applied to all hosts, not just one. This is also a very good improvement over the industry practice of online schema change, which also must run on all hosts. Since Vitess’s backup / restore and reparent processes are very reliable (they need to be reliable on their own, independently of this process!), this does not add much more complexity to a running system. + +## Update Stream + +Since the SBR replication stream also contains comments of which primary key is affected by a change, it is possible to look at the replication stream and know exactly what objects have changed. This Vitess feature is called [Update Stream](../update-stream). + +By subscribing to the Update Stream for a given shard, one can know what values change. This stream can be used to create a stream of data changes (export to an Apache Kafka for instance), or even invalidate an application layer cache. + +Note: the [Update Stream](../update-stream) only reliably contains the primary key values of the rows that have changed, not the actual values for all columns. To get these values, it is necessary to re-query the database. + +We have plans to make this Update Stream feature more consistent, very resilient, fast, and transparent to sharding. + +## Semi-Sync + +If you tell Vitess to enforce semi-sync ([semisynchronous replication](https://dev.mysql.com/doc/refman/8.0/en/replication-semisync.html)) by setting the `semi_sync` or `cross_cell` [durability policy](../../../../../docs/15.0/user-guides/configuration-basic/durability_policy), then the following will happen: + +* The master will only accept writes if it has at least one slave connected and sending semi-sync ACK. It will never fall back to asynchronous (not requiring ACKs) because of timeouts while waiting for ACK, nor because of having zero slaves connected (although it will fall back to asynchronous in case of shutdown, abrupt or graceful). + + This is important to prevent split brain (or alternate futures) in case of a network partition. If we can verify all slaves have stopped replicating, we know the old master is not accepting writes, even if we are unable to contact the old master itself. + +* Slaves of replica type will send semi-sync ACK. Slaves of rdonly type will not send ACK. This is because rdonly slaves are not eligible to be promoted to master, so we want to avoid the case where a rdonly slave is the single best candidate for election at the time of master failure (though a split brain is possible when all rdonly slaves have transactions that none of replica slaves have). + +These behaviors combine to give you the property that, in case of master failure, there is at least one other replica type slave that has every transaction that was ever reported to clients as having completed. You can then ([manually](../vtctl/#emergencyreparentshard)], or with an automated tool like [Orchestrator](https://github.com/github/orchestrator)) pick the replica that is farthest ahead in GTID position and promote that to be the new master. + +Thus, you can survive sudden master failure without losing any transactions that were reported to clients as completed. In MySQL 5.7+, this guarantee is strengthened slightly to preventing loss of any transactions that were ever **committed** on the original master, eliminating so-called [phantom reads](http://bugs.mysql.com/bug.php?id=62174). + +On the other hand these behaviors also give a requirement that each shard must have at least 2 tablets with type *replica* (with addition of the master that can be demoted to type *replica* this gives a minimum of 3 tablets with initial type *replica*). This will allow for the master to have a semi-sync acker when one of the replica tablets is down for any reason (for a version update, machine reboot, schema swap or anything else). + +With regard to replication lag, note that this does **not** guarantee there is always at least one replica type slave from which queries will always return up-to-date results. Semi-sync guarantees that at least one slave has the transaction in its relay log, but it has not necessarily been applied yet. The only way to guarantee a fully up-to-date read is to send the request to the master. + +See this [document](../row-based-replication) for more information. diff --git a/content/zh/docs/19.0/reference/vitess-sequences.md b/content/zh/docs/19.0/reference/vitess-sequences.md new file mode 100644 index 000000000..46d6388d5 --- /dev/null +++ b/content/zh/docs/19.0/reference/vitess-sequences.md @@ -0,0 +1,208 @@ +--- +title: Vitess Sequences +weight: 3 +--- + +This document describes the Vitess Sequences feature, and how to use it. + +## Motivation + +MySQL provides the `auto-increment` feature to assign monotonically incrementing +IDs to a column in a table. However, when a table is sharded across multiple +instances, maintaining the same feature is a lot more tricky. + +Vitess Sequences fill that gap: + +* Inspired from the usual SQL sequences (implemented in different ways by + Oracle, SQL Server and PostgreSQL). + +* Very high throughput for ID creation, using a configurable in-memory block allocation. + +* Transparent use, similar to MySQL auto-increment: when the field is omitted in + an `insert` statement, the next sequence value is used. + +## When *not* to Use Auto-Increment + +Before we go any further, an auto-increment column has limitations and +drawbacks. let's explore this topic a bit here. + +### Security Considerations + +Using auto-increment can leak confidential information about a service. Let's +take the example of a web site that store user information, and assign user IDs +to its users as they sign in. The user ID is then passed in a cookie for all +subsequent requests. + +The client then knows their own user ID. It is now possible to: + +* Try other user IDs and expose potential system vulnerabilities. + +* Get an approximate number of users of the system (using the user ID). + +* Get an approximate number of sign-ins during a week (creating two accounts a + week apart, and diffing the two IDs). + +Auto-incrementing IDs should be reserved for either internal applications, or +exposed to the clients only when safe. + +### Alternatives + +Alternative to auto-incrementing IDs are: + +* use a 64 bits random generator number. Try to insert a new row with that + ID. If taken (because the statement returns an integrity error), try another + ID. + +* use a UUID scheme, and generate truely unique IDs. + +Now that this is out of the way, let's get to MySQL auto-increment. + +## MySQL Auto-increment Feature + +Let's start by looking at the MySQL auto-increment feature: + +* A row that has no value for the auto-increment value will be given the next ID. + +* The current value is stored in the table metadata. + +* Values may be ‘burned’ (by rolled back transactions). + +* Inserting a row with a given value that is higher than the current value will + set the current value. + +* The value used by the master in a statement is sent in the replication stream, + so replicas will have the same value when re-playing the stream. + +* There is no strict guarantee about ordering: two concurrent statements may + have their commit time in one order, but their auto-incrementing ID in the + opposite order (as the value for the ID is reserved when the statement is + issued, not when the transaction is committed). + +* MySQL has multiple options for auto-increment, like only using every N number + (for multi-master configurations), or performance related features (locking + that table’s current ID may have concurrency implications). + +* When inserting a row in a table with an auto-increment column, if the value + for the auto-increment row is not set, the value for the column is returned to + the client alongside the statement result. + +## Vitess Sequences + +An early design was to use a single unsharded database and a table with an +auto-increment value to generate new values. However, this has serious +limitations, in particular throughtput, and storing one entry for each value in +that table, for no reason. + +So we decided instead to base sequences on a MySQL table, and use a single value +in that table to describe which values the sequence should have next. To +increase performance, we also support block allocation of IDs: each update to +the MySQL table is only done every N IDs (N being configurable), and in between +only memory structures in vttablet are updated, making the QPS only limited by +RPC latency. + +The sequence table then is an unsharded single row table that Vitess can use to generate monotonically increasing ids. The VSchema allows you to associate a column of a table with the sequence table. Once they are associated, an insert on that table will transparently fetch an id from the sequence table, fill in the value, and route the row to the appropriate shard. + +Since sequences are unsharded tables, they will be stored in the database (in our tutorial example, this is the commerce database). + +The final goal is to have Sequences supported with SQL statements, like: + +``` sql +/* DDL support */ +CREATE SEQUENCE my_sequence; + +SELECT NEXT VALUE FROM my_sequence; + +ALTER SEQUENCE my_sequence ...; + +DROP SEQUENCE my_sequence; + +SHOW CREATE SEQUENCE my_sequence; +``` + +In the current implementation, we support the query access to Sequences, but not +the administration commands yet. + +### Creating a Sequence + +*Note*: The names in this section are extracted from the examples/demo sample +application. + +To create a Sequence, a backing table must first be created and initialized with a single row. The columns for that table have to be respected. + +This is an example: + +``` sql +create table user_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; + +insert into user_seq(id, next_id, cache) values(0, 1, 100); +``` + +Then, the Sequence has to be defined in the VSchema for that keyspace: + +``` json +{ + "sharded": false, + "tables": { + "user_seq": { + "type": "sequence" + }, + ... + } +} +``` + +And the table it is going to be using it can also reference the Sequence in its VSchema: + +``` json +{ + ... + "tables" : { + "user": { + "column_vindexes": [ + ... + ], + "auto_increment": { + "column": "user_id", + "sequence": "user_seq" + } + }, +``` + +After this done (and the Schema has been reloaded on master tablet, and the +VSchema has been pushed), the sequence can be used. + +### Accessing a Sequence + +If a Sequence is used to fill in a column for a table, nothing further needs to +be done. Just sending no value for the column will make vtgate insert the next +Sequence value in its place. + +It is also possible to access the Sequence directly with the following SQL constructs: + +``` sql +/* Returns the next value for the sequence */ +select next value from my_sequence; + +/* Returns the next value for the sequence, and also reserve 4 values after that. */ +select next 5 values from my_sequence; + +``` + +## TO-DO List + +### DDL Support + +We want to add DDL support for sequences, as previously mentioned: + +``` sql +CREATE SEQUENCE my_sequence; + +ALTER SEQUENCE my_sequence ...; + +DROP SEQUENCE my_sequence; + +SHOW CREATE SEQUENCE my_sequence; +``` + +But for now, the Sequence backing table has to be created and managed using the +usual schema management features, with the right column definitions and table comment. diff --git a/content/zh/docs/19.0/reference/vreplication.md b/content/zh/docs/19.0/reference/vreplication.md new file mode 100644 index 000000000..b873f6029 --- /dev/null +++ b/content/zh/docs/19.0/reference/vreplication.md @@ -0,0 +1,434 @@ +--- +title: VReplication Operator's Guide +--- + +VReplication is a core component of vitess that can be used to compose +many features. It can be used for the following use cases: + +* **Resharding**: Legacy workflows of vertical and horizontal resharding. + New workflows of resharding from an unsharded to a sharded keyspace and + vice-versa. Resharding from an unsharded to an unsharded keyspace using + a different vindex than the source keyspace. +* **Materialized Views**: You can specify a materialization rule that creates + a view of the source table into a target keyspace. This materialization + can use a different primary vindex than the source. It can also materialize + a subset of the source columns, or add new expressions from the source. + This view will be kept up-to-date in real time. One can also materialize + reference tables onto all shards and have vitess perform efficient + local joins with those materialized tables. +* **Realtime rollups**; The materialization expression can include aggregation + expressions in which case, vitess will create a rolled up version of the + source table which can be used for realtime analytics. +* **Backfilling lookup vindexes**: VReplication can be used to backfill a + newly created lookup vindex. Workflows can be built to manage the switching + from a backfill mode to the vindex itself keeping it up-to-date. +* **Schema deployment**: We can use VReplication to recreate the workflow + performed by gh-ost and thereby support zero-downtime schema deployments + in vitess natively. +* **Data migration**: VReplication can be setup to migrate data from an + existing system into vitess. The replication could also be reversed after + a cutover giving you the option to rollback a migration if something went + wrong. +* **Change notification**: The streamer component of VReplication can be + used for the application or a systems operator to subscribe to change + notification and use it to keep downstream systems up-to-date with the + source. + +The VReplication feature itself is a fairly low level one that is +expected to be used as a building block for the above use cases. However, +it's still possible to directly issue commands to do some of the +activities. + +## Feature description + +VReplication works as a stream or combination of streams. Each stream +establishes a replication from a source keyspace/shard into a target +keyspace/shard. + +A given stream can replicate multiple tables. For each table, you can +specify a `select` statement that represents both the transformation +rule and the filtering rule. The select expressions specify the +transformation, and the where clause specifies the filtering. + +The select expressions can be any non-aggregate mysql expression, or +they can also be `count` or `sum` as aggregate expressions. Aggregate +expressions combined with the corresponding `group by` clauses will +allow you to materialize real-time rollups of the source table, which +can be used for analytics. The target table can have a different name +from the source. + +For a sharded system like vitess, multiple VReplication streams +may be needed to achieve the necessary goals. This is because there +will be multiple source shards as well as destination shards, and +the relationship between them may not be one to one. + +VReplication performs the following essential functions: + +* Copy data from the source to the destination table in a consistent + fashion. For large data, this copy can be long-running. It can be + interrupted and resumed. If interrupted, VReplication can keep + the copied portion up-to-date with respect to the source, and it + can resume the copy process + at a point that's consistent with the current replication position. +* After copying is finished, it can continuously replicate the data + from the source to destination. +* The copying rule can be expressed as a `select` statement. The + statement should be simple enough that the materialized table can + be kept up-to-date from the data coming from the binlog. For + example, joins are not supported. +* Correctness verification (to be implemented): VReplication can + verify that the target table is an exact representation of + the select statement from the source by capturing consistent + snapshots of the source and target and comparing them against each + other. This step can be done without the need to create special + snapshot replicas. +* Journaling (to be implemented): If there is any kind of traffic + cut-over where we start writing to a different table than we used + to before, VReplication will save the current binlog positions + into a journal table. This can be used by other streams to resume + replication from the new source. +* Routing rules: Although this feature is itself not a direct + functionality of VReplication, it works hand in hand with it. It allows + you to specify sophisticated rules about where to route queries + depending on the type of workflow being performed. For example, + it can be used to control the cut-over during resharding. + +## VReplicationExec + +The `VReplicationExec` command is used to manage vreplication streams. +The commands are issued as SQL statements. For example, a `select` +can be used to see the current list of streams. An `insert` can +be used to create one, etc. By design, the metadata for vreplication +streams are stored in a `vreplication` table in the `vt` database. +VReplication uses the 'pull' model. This means that a stream is +created on the target side, and the target pulls the data by finding +the appropriate source. + +The table schema is as follows: + +``` +CREATE TABLE _vt.vreplication ( + id INT AUTO_INCREMENT, + workflow VARBINARY(1000), + source VARBINARY(10000) NOT NULL, + pos VARBINARY(10000) NOT NULL, + stop_pos VARBINARY(10000) DEFAULT NULL, + max_tps BIGINT(20) NOT NULL, + max_replication_lag BIGINT(20) NOT NULL, + cell VARBINARY(1000) DEFAULT NULL, + tablet_types VARBINARY(100) DEFAULT NULL, + time_updated BIGINT(20) NOT NULL, + transaction_timestamp BIGINT(20) NOT NULL, + state VARBINARY(100) NOT NULL, + message VARBINARY(1000) DEFAULT NULL, + db_name VARBINARY(255) NOT NULL, + PRIMARY KEY (id) +) +``` + +The fields are explained in the following section. + +This is the syntax of the command: + +``` +VReplicationExec [--json] +``` + +Here's an example of the command to list all existing streams for +a given tablet. + +``` +lvtctl.sh VReplicationExec 'tablet-100' 'select * from _vt.vreplication' +``` + +### Creating a stream + +It's generally easier to send the VReplication command programmatically +instead of a bash script. This is because of the number of nested encodings +involved: + +* One of the arguments is an SQL statement, which can contain quoted + strings as values. +* One of the strings in the SQL statement is a string encoded protobuf, + which can contain quotes. +* One of the parameters within the protobuf is an SQL select expression + for the materialized view. + +However, you can use [vreplgen.go](https://github.com/vitessio/contrib/blob/master/vreplgen/vreplgen.go) to generate a fully escaped bash command. + +Alternately, you can use a python program. Here's an example: + +```python +cmd = [ + './lvtctl.sh', + 'VReplicationExec', + 'test-200', + """insert into _vt.vreplication + (db_name, source, pos, max_tps, max_replication_lag, tablet_types, time_updated, transaction_timestamp, state) values + ('vt_keyspace', 'keyspace:"lookup" shard:"0" filter: >', '', 99999, 99999, 'master', 0, 0, 'Running')""", +] +``` + +The first argument to the command is the master tablet id of the target keyspace/shard. + +The second argument is the SQL command. To start a new stream, you need an insert statement. +The parameters are as follows: + +* `db_name`: This name must match the name of the mysql database. In the future, this + will not be required, and will be automatically filled in by the vttablet. +* `source`: The protobuf representation of the stream source, explained below. +* `pos`: For a brand new stream, this should be empty. To start + from a specific position, a flavor-encoded position must be specified. A + typical position would look like this `MySQL56/ac6c45eb-71c2-11e9-92ea-0a580a1c1026:1-1296`. +* `max_tps`: 99999, reserved. +* `max_replication_lag`: 99999, reserved. +* `tablet_types`: specifies a comma separated list of tablet types to replicate from. + If empty, the default tablet type specified by the `-vreplication_tablet_type` + command line flag is used. +* `time_updated`: 0, reserved. +* `transaction_timestamp`: 0, reserved. +* `state`: 'Running' or 'Stopped'. +* `cell`: is an optional parameter that specifies the cell from which the stream + can be sourced. + +#### The source field + +The source field is a proto-encoding of the following structure: + +``` +message BinlogSource { + // the source keyspace + string keyspace = 1; + // the source shard + string shard = 2; + // list of filtering rules + Filter filter = 6; + // what to do if a DDL is encountered + OnDDLAction on_ddl = 7; +} + +message Filter { + repeated Rule rules = 1; +} + +message Rule { + // match can be a table name or a regular expression + // delineated by '/' and '/'. + string match = 1; + // filter can be an empty string or keyrange if the match + // is a regular expression. Otherwise, it must be a select + // query. + string filter = 2; +} + +enum OnDDLAction { + IGNORE = 0; + STOP = 1; + EXEC = 2; + EXEC_IGNORE = 3; +} +``` + +Here are some examples of proto encodings: + +``` +keyspace:"lookup" shard:"0" filter: > +``` + +Meaning: replicate all columns and rows of product from `lookup/0.product` +into the `uproduct` table in target keyspace. + +``` +keyspace:"user" shard:"-80" filter: > +``` + +The double-backslash for the strings inside the select will first be escaped by the python script, +which will cause the expression to internally be `\'unicode_loose_md5\'`. Since the entire +source is surrounded by single quotes when being sent as a value inside the outer insert statement, +the single `\` will escape the single quotes that follow. The final value in the source will +therefore be: + + +``` +keyspace:"user" shard:"-80" filter: > +``` + +Meaning: replicate all columns of `user/-80.uorder` where `unicode_loose_md5(mname)` +is within `-80` keyrange, into `morder`. + +This particular stream generally wouldn't make sense in isolation. This would typically +be one of four streams that combine together to create a materialized view of `uorder` +from the `user` keyspace into the target (`merchant`) keyspace, but sharded by using +`mname` as the primary vindex. The vindex used would be `unicode_loose_md5` which should +also match the primary vindex of other tables in the target keyspace. + +``` +keyspace:"user" shard:"-80" filter: > +``` + +Meaning: create a materialized view of `user/-80.uorder` into `sales` of the target +keyspace using the expression: `select pid, count(*) as kount, sum(price) as amount from uorder group by pid`. + +This represents only one stream from source shard `-80`. Presumably, there will be one +more for the other `-80` shard. + +#### The 'select' features + +The select statement has the following features (and restrictions): + +* The Select expressions can be any deterministic mysql expression. + Subqueries are not supported. Among aggregate expressions, only + `count(*)` and `sum(col)` are supported. +* The where clause can only contain the `in_keyrange` construct. It + has two forms: + * `in_keyrange('-80')`: The row's source keyrange matched against `-80`. + * `in_keyrange(col, 'hash', '-80')`: The keyrange is computed using + `hash(col)` and matched against `-80`. +* `group by`: can be specified if using aggregations. The group by + expressions are expected to cover the non-aggregated columns just + like regular SQL requires. +* No other constructs like `order by`, `limit`, joins, etc. are allowed. + +#### The pos field + +For starting a brand new vreplication stream, the `pos` field must be empty. +The empty string signifies that there's no starting point for the vreplication. +This causes VReplication to copy the contents of the source table first, and then +start the replication. + +For large tables, this is done in chunks. After each chunk is copied, replication +is resumed until it's caught up. VReplication ensures that only changes that affect +existing rows are applied. Following this another chunk is copied, and so on, +until all tables are completed. After that, replication runs indefinitely. + +#### It's a shared row + +The vreplication row is shared between the operator and Vreplication itself. +Once the row is created, the VReplication stream +updates various fields of the row to save and report on its own status. For example, the +`pos` field is continuously updated as it makes forward progress. + +While copying, the `state` field is updated as `Init` or `Copying`. + +### Updating a stream + +You can change any field of the stream by issuing a `VReplicationExec` with an +`update` statement. You are required to specify the id of the row you intend to +update. You can only update one row at a time. + +Typically, you can update the row and change the state to `Stopping` to stop a +stream, or to `Running` to restart a stopped stream. + +You can also update the row to set a `stop_pos`, which will make the replication +stop once it reaches the specified position. + +### Deleting a stream + +You can delete a stream by issuing a `delete` statement. This will stop the replication +and delete the row. This statement is destructive. All data about the replication +state will be permanently deleted. + +## Other properties of VReplication + +### Fast replay + +VReplication has the capability to batch transactions if the send rate of the source +exceeds the replay rate of the destination. This allows it to catch up very quickly +when there is a backlog. Load tests have shown a 3-20X improvement over traditional +MySQL replication depending on the workload. + +### Accurate lag tracking + +The source vttablet sends its current time along with every event. This allows the +target to correct for clock skew while estimating replication lag. Additionally, +the source starts sending heartbeats if there is nothing to send. If the target +receives no events from the source at all, it knows that it's definitely lagged +and starts reporting itself accordingly. + +### Self-replication + +VReplication allows you to set the source keyspace/shard to be the same as the target. +This is especially useful for performing schema rollouts: you can create the target +table with the intended schema and vreplicate from the source table to the new +target. Once caught up, you can cutover to write to the target table. +In this situation, an apply on +the target generates a binlog event that will be picked up by the source and +sent to the target. Typically, it will be an empty transaction. In such cases, +the target does not generally apply these transactions, because such an application +will generate yet another event. However, there are situations where one needs +to apply empty transactions, especially if it's a required stopping point. +VReplication can differentiate between these situations and apply events +only as needed. + +### Deadlocks and lock wait timeouts + +It is possible that multiple streams can conflict with each other and cause +deadlocks or lock waits. When such things happen, VReplication silently retries +such transactions without reporting an error. It does increment a counter so +that the frequency of such occurrences can be tracked. + +### Automatic retries + +If any other error is encountered, the replication is retried after a short wait. +Each time, the stream searches from the full list of available sources and picks +one at random. + +### on\_ddl + +The source specification allows you to specify a value for on\_ddl. The values +can be as follows: + +* `IGNORE`: Ignore all DDLs. +* `STOP`: Stop when DDL is encountered. This allows you to make any necessary + changes to the target. Once changes are made, updating the state to `Running` + will cause VReplication to continue from just after the point where it + encountered the DDL. +* `EXEC`: Apply the DDL, but stop if an error is encountered while applying it. +* `EXEC_IGNORE`: Apply the DDL, but ignore any errors and continue replicating. + +### Failover continuation + +If a failover is performed on the target keyspace/shard, the new master will +automatically resume VReplication from where the previous master left off. + +## Monitoring and troubleshooting + +### VTTablet /debug/status + +The first place to look at is the `/debug/status` page of the target master +vttablet. The bottom of the page shows the status of all the VReplication +streams. + +Typically, if there is a problem, the `Last Message` column will display the +error. Sometimes, it's possible that the stream cannot find a source. If so, +the `Source Tablet` would be empty. + +### VTTablet logfile + +If the errors are not clear or if they keep disappearing, the VTTablet logfile +will contain information about what it's been doing with each stream. + +### VReplicationExec select + +The current status of the streams can also be fetched by issuing a +VReplicationExec command with `select * from _vt.vreplication`. + +### Monitoring variables + +VReplication also reports the following variables that can be scraped by +monitoring tools like prometheus: + +* VReplicationStreamCount: Number of vreplication streams. +* VReplicationSecondsBehindMasterMax: Max vreplication seconds behind master. +* VReplicationSecondsBehindMaster: VReplication seconds behind master per stream. +* VReplicationSource: The source for each VReplication stream. +* VReplicationSourceTablet: The source tablet for each VReplication stream. +* RowStreamerMaxInnoDBTrxHistLen: Max length of the InnoDB transaction history list on a source tablet before streaming a batch of rows when copying a table. + * This can be modified in the running server at the `/debug/env` endpoint. +* RowStreamerMaxMySQLReplLagSecs: Max MySQL replication lag on a source tablet before streaming a batch of rows when copying a table. + * This can be modified in the running server at the `/debug/env` endpoint. +* RowStreamerWaits: The total number of times we've waited, and how long we've waited, for MySQL to fall below the `RowStreamerMax*` values on a source tablet when preparing to stream a batch of rows when copying a table. + * This can be seen on a per table basis in `VStreamerPhaseTiming`. + +Thresholds and alerts can be set to draw attention to potential problems. + diff --git a/content/zh/docs/19.0/reference/vtctl.md b/content/zh/docs/19.0/reference/vtctl.md new file mode 100644 index 000000000..2cdbdf62a --- /dev/null +++ b/content/zh/docs/19.0/reference/vtctl.md @@ -0,0 +1,2449 @@ +--- +title: vtctl Reference +noToc: true +weight: 2 +featured: true +--- + +This reference guide explains the commands that the vtctl tool supports. **vtctl** is a command-line tool used to administer a Vitess cluster, and it allows a human or application to easily interact with a Vitess implementation. + +Commands are listed in the following groups: + +* [Cells](#cells) +* [Generic](#generic) +* [Keyspaces](#keyspaces) +* [Queries](#queries) +* [Replication Graph](#replication-graph) +* [Resharding Throttler](#resharding-throttler) +* [Schema, Version, Permissions](#schema-version-permissions) +* [Serving Graph](#serving-graph) +* [Shards](#shards) +* [Tablets](#tablets) +* [Topo](#topo) + +## Cells + +* [AddCellInfo](#addcellinfo) +* [DeleteCellInfo](#deletecellinfo) +* [GetCellInfo](#getcellinfo) +* [GetCellInfoNames](#getcellinfonames) +* [UpdateCellInfo](#updatecellinfo) + +### AddCellInfo + +Registers a local topology service in a new cell by creating the CellInfo with the provided parameters. The address will be used to connect to the topology service, and we'll put Vitess data starting at the provided root. + +#### Example + +
    AddCellInfo [-server_address <addr>] [-root <root>] <cell>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| root | string | The root path the topology server is using for that cell. | +| server_address | string | The address the topology server is using for that cell. | + + +#### Arguments + +* <addr> – Required. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <AddCellInfo> command This error occurs if the command is not called with exactly one argument. + + +### DeleteCellInfo + +Deletes the CellInfo for the provided cell. The cell cannot be referenced by any Shard record. + +#### Example + +
    DeleteCellInfo <cell>
    + +#### Errors + +* the <cell> argument is required for the <DeleteCellInfo> command This error occurs if the command is not called with exactly one argument. + + +### GetCellInfo + +Prints a JSON representation of the CellInfo for a cell. + +#### Example + +
    GetCellInfo <cell>
    + +#### Errors + +* the <cell> argument is required for the <GetCellInfo> command This error occurs if the command is not called with exactly one argument. + + +### GetCellInfoNames + +Lists all the cells for which we have a CellInfo object, meaning we have a local topology service registered. + +#### Example + +
    GetCellInfoNames
    + +#### Errors + +* <GetCellInfoNames> command takes no parameter This error occurs if the command is not called with exactly 0 arguments. + + +### UpdateCellInfo + +Updates the content of a CellInfo with the provided parameters. If a value is empty, it is not updated. The CellInfo will be created if it doesn't exist. + +#### Example + +
    UpdateCellInfo [-server_address <addr>] [-root <root>] <cell>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| root | string | The root path the topology server is using for that cell. | +| server_address | string | The address the topology server is using for that cell. | + + +#### Arguments + +* <addr> – Required. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <UpdateCellInfo> command This error occurs if the command is not called with exactly one argument. + + +## Generic + +* [ListAllTablets](#listalltablets) +* [ListTablets](#listtablets) +* [Validate](#validate) + +### ListAllTablets + +Lists all tablets in an awk-friendly way. + +#### Example + +
    ListAllTablets <cell name>
    + +#### Arguments + +* <cell name> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell name> argument is required for the <ListAllTablets> command This error occurs if the command is not called with exactly one argument. + + +### ListTablets + +Lists specified tablets in an awk-friendly way. + +#### Example + +
    ListTablets <tablet alias> ...
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <tablet alias> argument is required for the <ListTablets> command This error occurs if the command is not called with at least one argument. + + +### Validate + +Validates that all nodes reachable from the global replication graph and that all tablets in all discoverable cells are consistent. + +#### Example + +
    Validate [-ping-tablets]
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | + + + + +## Keyspaces + +* [CreateKeyspace](#createkeyspace) +* [DeleteKeyspace](#deletekeyspace) +* [FindAllShardsInKeyspace](#findallshardsinkeyspace) +* [GetKeyspace](#getkeyspace) +* [GetKeyspaces](#getkeyspaces) +* [MigrateServedFrom](#migrateservedfrom) +* [MigrateServedTypes](#migrateservedtypes) +* [CancelResharding](#cancelresharding) +* [ShowResharding](#showresharding) +* [RebuildKeyspaceGraph](#rebuildkeyspacegraph) +* [RemoveKeyspaceCell](#removekeyspacecell) +* [SetKeyspaceServedFrom](#setkeyspaceservedfrom) +* [SetKeyspaceShardingInfo](#setkeyspaceshardinginfo) +* [ValidateKeyspace](#validatekeyspace) +* [WaitForDrain](#waitfordrain) + +### CreateKeyspace + +Creates the specified keyspace. + +#### Example + +
    CreateKeyspace [-sharding_column_name=name] [-sharding_column_type=type] [-served_from=tablettype1:ks1,tablettype2,ks2,...] [-force] <keyspace name>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the keyspace already exists | +| served_from | string | Specifies a comma-separated list of dbtype:keyspace pairs used to serve traffic | +| sharding_column_name | string | Specifies the column to use for sharding operations | +| sharding_column_type | string | Specifies the type of the column to use for sharding operations | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace name> argument is required for the <CreateKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### DeleteKeyspace + +Deletes the specified keyspace. In recursive mode, it also recursively deletes all shards in the keyspace. Otherwise, there must be no shards left in the keyspace. + +#### Example + +
    DeleteKeyspace [-recursive] <keyspace>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| recursive | Boolean | Also recursively delete all shards in the keyspace. | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* must specify the <keyspace> argument for <DeleteKeyspace> This error occurs if the command is not called with exactly one argument. + + +### FindAllShardsInKeyspace + +Displays all of the shards in the specified keyspace. + +#### Example + +
    FindAllShardsInKeyspace <keyspace>
    + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the <FindAllShardsInKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### GetKeyspace + +Outputs a JSON structure that contains information about the Keyspace. + +#### Example + +
    GetKeyspace <keyspace>
    + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the <GetKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### GetKeyspaces + +Outputs a sorted list of all keyspaces. + + +### MigrateServedFrom + +Makes the <destination keyspace/shard> serve the given type. This command also rebuilds the serving graph. + +#### Example + +
    MigrateServedFrom [-cells=c1,c2,...] [-reverse] <destination keyspace/shard> <served tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | +| filtered_replication_wait_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations | +| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble | + + +#### Arguments + +* <destination keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <destination keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedFrom> command This error occurs if the command is not called with exactly 2 arguments. + + +### MigrateServedTypes + +Migrates a serving type from the source shard to the shards that it replicates to. This command also rebuilds the serving graph. The <keyspace/shard> argument can specify any of the shards involved in the migration. + +#### Example + +
    MigrateServedTypes [-cells=c1,c2,...] [-reverse] [-skip-refresh-state] <keyspace/shard> <served tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | +| filtered\_replication\_wait\_time | Duration | Specifies the maximum time to wait, in seconds, for filtered replication to catch up on master migrations | +| reverse | Boolean | Moves the served tablet type backward instead of forward. Use in case of trouble | +| skip-refresh-state | Boolean | Skips refreshing the state of the source tablets after the migration, meaning that the refresh will need to be done manually, replica and rdonly only) | +| reverse\_replication | Boolean | For master migration, enabling this flag reverses replication which allows you to rollback | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <source keyspace/shard> and <served tablet type> arguments are both required for the <MigrateServedTypes> command This error occurs if the command is not called with exactly 2 arguments. +* the <skip-refresh-state> flag can only be specified for non-master migrations + + +### CancelResharding + +Permanently cancels a resharding in progress. All resharding related metadata will be deleted. + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + + +### ShowResharding + +"Displays all metadata about a resharding in progress. + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + + +### RebuildKeyspaceGraph + +Rebuilds the serving data for the keyspace. This command may trigger an update to all connected clients. + +#### Example + +
    RebuildKeyspaceGraph [-cells=c1,c2,...] <keyspace> ...
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <keyspace> argument must be used to specify at least one keyspace when calling the <RebuildKeyspaceGraph> command This error occurs if the command is not called with at least one argument. + + +### RemoveKeyspaceCell + +Removes the cell from the Cells list for all shards in the keyspace, and the SrvKeyspace for that keyspace in that cell. + +#### Example + +
    RemoveKeyspaceCell [-force] [-recursive] <keyspace> <cell>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | +| recursive | Boolean | Also delete all tablets in that cell belonging to the specified keyspace. | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <keyspace> and <cell> arguments are required for the <RemoveKeyspaceCell> command This error occurs if the command is not called with exactly 2 arguments. + + +### SetKeyspaceServedFrom + +Changes the ServedFromMap manually. This command is intended for emergency fixes. This field is automatically set when you call the *MigrateServedFrom* command. This command does not rebuild the serving graph. + +#### Example + +
    SetKeyspaceServedFrom [-source=<source keyspace name>] [-remove] [-cells=c1,c2,...] <keyspace name> <tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to affect | +| remove | Boolean | Indicates whether to add (default) or remove the served from record | +| source | string | Specifies the source keyspace name | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <keyspace name> and <tablet type> arguments are required for the <SetKeyspaceServedFrom> command This error occurs if the command is not called with exactly 2 arguments. + + +### SetKeyspaceShardingInfo + +Updates the sharding information for a keyspace. + +#### Example + +
    SetKeyspaceShardingInfo [-force] <keyspace name> [<column name>] [<column type>]
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Updates fields even if they are already set. Use caution before calling this command. | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. +* <column name> – Optional. +* <column type> – Optional. + +#### Errors + +* the <keyspace name> argument is required for the <SetKeyspaceShardingInfo> command. The <column name> and <column type> arguments are both optional This error occurs if the command is not called with between 1 and 3 arguments. +* both <column name> and <column type> must be set, or both must be unset + + +### ValidateKeyspace + +Validates that all nodes reachable from the specified keyspace are consistent. + +#### Example + +
    ValidateKeyspace [-ping-tablets] <keyspace name>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Specifies whether all tablets will be pinged during the validation process | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace name> argument is required for the <ValidateKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### WaitForDrain + +Blocks until no new queries were observed on all tablets with the given tablet type in the specified keyspace. This can be used as sanity check to ensure that the tablets were drained after running vtctl MigrateServedTypes and vtgate is no longer using them. If -timeout is set, it fails when the timeout is reached. + +#### Example + +
    WaitForDrain [-timeout <duration>] [-retry_delay <duration>] [-initial_wait <duration>] <keyspace/shard> <served tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to look for tablets | +| initial_wait | Duration | Time to wait for all tablets to check in | +| retry_delay | Duration | Time to wait between two checks | +| timeout | Duration | Timeout after which the command fails | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <keyspace/shard> and <tablet type> arguments are both required for the <WaitForDrain> command This error occurs if the command is not called with exactly 2 arguments. + + +## Queries + +* [VtGateExecute](#vtgateexecute) +* [VtGateExecuteKeyspaceIds](#vtgateexecutekeyspaceids) +* [VtGateExecuteShards](#vtgateexecuteshards) +* [VtGateSplitQuery](#vtgatesplitquery) +* [VtTabletBegin](#vttabletbegin) +* [VtTabletCommit](#vttabletcommit) +* [VtTabletExecute](#vttabletexecute) +* [VtTabletRollback](#vttabletrollback) +* [VtTabletStreamHealth](#vttabletstreamhealth) +* [VtTabletUpdateStream](#vttabletupdatestream) + +### VtGateExecute + +Executes the given SQL query with the provided bound variables against the vtgate server. + +#### Example + +
    VtGateExecute -server <vtgate> [-bind_variables <JSON map>] [-keyspace <default keyspace>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| json | Boolean | Output JSON instead of human-readable table | +| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | +| server | string | VtGate server to connect to | +| target | string | keyspace:shard@tablet_type | + + +#### Arguments + +* <vtgate> – Required. +* <sql> – Required. + +#### Errors + +* the <sql> argument is required for the <VtGateExecute> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* error connecting to vtgate '%v': %v +* Execute failed: %v + + +### VtGateExecuteKeyspaceIds + +Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the shards that contain the provided keyspace ids. + +#### Example + +
    VtGateExecuteKeyspaceIds -server <vtgate> -keyspace <keyspace> -keyspace_ids <ks1 in hex>,<k2 in hex>,... [-bind_variables <JSON map>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| json | Boolean | Output JSON instead of human-readable table | +| keyspace | string | keyspace to send query to | +| keyspace_ids | string | comma-separated list of keyspace ids (in hex) that will map into shards to send query to | +| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | +| server | string | VtGate server to connect to | +| tablet_type | string | tablet type to query | + + +#### Arguments + +* <vtgate> – Required. +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. +* <ks1 in hex> – Required. To specify multiple values for this argument, separate individual values with a comma. +* <sql> – Required. + +#### Errors + +* the <sql> argument is required for the <VtGateExecuteKeyspaceIds> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot hex-decode value %v '%v': %v +* error connecting to vtgate '%v': %v +* Execute failed: %v + + +### VtGateExecuteShards + +Executes the given SQL query with the provided bound variables against the vtgate server. It is routed to the provided shards. + +#### Example + +
    VtGateExecuteShards -server <vtgate> -keyspace <keyspace> -shards <shard0>,<shard1>,... [-bind_variables <JSON map>] [-tablet_type <tablet type>] [-options <proto text options>] [-json] <sql>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| json | Boolean | Output JSON instead of human-readable table | +| keyspace | string | keyspace to send query to | +| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | +| server | string | VtGate server to connect to | +| shards | string | comma-separated list of shards to send query to | +| tablet_type | string | tablet type to query | + + +#### Arguments + +* <vtgate> – Required. +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. +* <shard> – Required. The name of a shard. The argument value is typically in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a comma. +* <sql> – Required. + +#### Errors + +* the <sql> argument is required for the <VtGateExecuteShards> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* error connecting to vtgate '%v': %v +* Execute failed: %v + + +### VtGateSplitQuery + +Executes the SplitQuery computation for the given SQL query with the provided bound variables against the vtgate server (this is the base query for Map-Reduce workloads, and is provided here for debug / test purposes). + +#### Example + +
    VtGateSplitQuery -server <vtgate> -keyspace <keyspace> [-split_column <split_column>] -split_count <split_count> [-bind_variables <JSON map>] <sql>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| algorithm | string | The algorithm to | +| keyspace | string | keyspace to send query to | +| server | string | VtGate server to connect to | +| split_count | Int64 | number of splits to generate. | + + +#### Arguments + +* <vtgate> – Required. +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. +* <split_count> – Required. +* <sql> – Required. + +#### Errors + +* the <sql> argument is required for the <VtGateSplitQuery> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* Exactly one of <split_count> or num_rows_per_query_part +* Unknown split-query <algorithm>: %v +* error connecting to vtgate '%v': %v +* Execute failed: %v +* SplitQuery failed: %v + + +### VtTabletBegin + +Starts a transaction on the provided server. + +#### Example + +
    VtTabletBegin [-username <TableACL user>] <tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet_alias> argument is required for the <VtTabletBegin> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v +* Begin failed: %v + + +### VtTabletCommit + +Commits the given transaction on the provided server. + +#### Example + +
    VtTabletCommit [-username <TableACL user>] <transaction_id>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <transaction_id> – Required. + +#### Errors + +* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletCommit> command This error occurs if the command is not called with exactly 2 arguments. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v + + +### VtTabletExecute + +Executes the given query on the given tablet. -transaction_id is optional. Use VtTabletBegin to start a transaction. + +#### Example + +
    VtTabletExecute [-username <TableACL user>] [-transaction_id <transaction_id>] [-options <proto text options>] [-json] <tablet alias> <sql>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| json | Boolean | Output JSON instead of human-readable table | +| options | string | execute options values as a text encoded proto of the ExecuteOptions structure | +| transaction_id | Int | transaction id to use, if inside a transaction. | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <sql> – Required. + +#### Errors + +* the <tablet_alias> and <sql> arguments are required for the <VtTabletExecute> command This error occurs if the command is not called with exactly 2 arguments. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v +* Execute failed: %v + + +### VtTabletRollback + +Rollbacks the given transaction on the provided server. + +#### Example + +
    VtTabletRollback [-username <TableACL user>] <tablet alias> <transaction_id>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| username | string | If set, value is set as immediate caller id in the request and used by vttablet for TableACL check | + + +#### Arguments + +* <TableACL user> – Required. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <transaction_id> – Required. + +#### Errors + +* the <tablet_alias> and <transaction_id> arguments are required for the <VtTabletRollback> command This error occurs if the command is not called with exactly 2 arguments. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v + + +### VtTabletStreamHealth + +Executes the StreamHealth streaming query to a vttablet process. Will stop after getting <count> answers. + +#### Example + +
    VtTabletStreamHealth [-count <count, default 1>] <tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| count | Int | number of responses to wait for | + + +#### Arguments + +* <count default 1> – Required. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <VtTabletStreamHealth> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v + + +### VtTabletUpdateStream + +Executes the UpdateStream streaming query to a vttablet process. Will stop after getting <count> answers. + +#### Example + +
    VtTabletUpdateStream [-count <count, default 1>] [-position <position>] [-timestamp <timestamp>] <tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| count | Int | number of responses to wait for | +| position | string | position to start the stream from | +| timestamp | Int | timestamp to start the stream from | + + +#### Arguments + +* <count default 1> – Required. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <VtTabletUpdateStream> command This error occurs if the command is not called with exactly one argument. +* query commands are disabled (set the -enable_queries flag to enable) +* cannot connect to tablet %v: %v + + +## Replication Graph + +* [GetShardReplication](#getshardreplication) + +### GetShardReplication + +Outputs a JSON structure that contains information about the ShardReplication. + +#### Example + +
    GetShardReplication <cell> <keyspace/shard>
    + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <cell> and <keyspace/shard> arguments are required for the <GetShardReplication> command This error occurs if the command is not called with exactly 2 arguments. + + +## Resharding Throttler + +* [GetThrottlerConfiguration](#getthrottlerconfiguration) +* [ResetThrottlerConfiguration](#resetthrottlerconfiguration) +* [ThrottlerMaxRates](#throttlermaxrates) +* [ThrottlerSetMaxRate](#throttlersetmaxrate) +* [UpdateThrottlerConfiguration](#updatethrottlerconfiguration) + +### GetThrottlerConfiguration + +Returns the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be returned. + +#### Example + +
    GetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <throttler name> – Optional. + +#### Errors + +* the <GetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments. +* error creating a throttler client for <server> '%v': %v +* failed to get the throttler configuration from <server> '%v': %v + + +### ResetThrottlerConfiguration + +Resets the current configuration of the MaxReplicationLag module. If no throttler name is specified, the configuration of all throttlers will be reset. + +#### Example + +
    ResetThrottlerConfiguration -server <vtworker or vttablet> [<throttler name>]
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <throttler name> – Optional. + +#### Errors + +* the <ResetThrottlerConfiguration> command accepts only <throttler name> as optional positional parameter This error occurs if the command is not called with more than 1 arguments. +* error creating a throttler client for <server> '%v': %v +* failed to get the throttler configuration from <server> '%v': %v + + +### ThrottlerMaxRates + +Returns the current max rate of all active resharding throttlers on the server. + +#### Example + +
    ThrottlerMaxRates -server <vtworker or vttablet>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. + +#### Errors + +* the ThrottlerSetMaxRate command does not accept any positional parameters This error occurs if the command is not called with exactly 0 arguments. +* error creating a throttler client for <server> '%v': %v +* failed to get the throttler rate from <server> '%v': %v + + +### ThrottlerSetMaxRate + +Sets the max rate for all active resharding throttlers on the server. + +#### Example + +
    ThrottlerSetMaxRate -server <vtworker or vttablet> <rate>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <rate> – Required. + +#### Errors + +* the <rate> argument is required for the <ThrottlerSetMaxRate> command This error occurs if the command is not called with exactly one argument. +* failed to parse rate '%v' as integer value: %v +* error creating a throttler client for <server> '%v': %v +* failed to set the throttler rate on <server> '%v': %v + + +### UpdateThrottlerConfiguration + +Updates the configuration of the MaxReplicationLag module. The configuration must be specified as protobuf text. If a field is omitted or has a zero value, it will be ignored unless -copy_zero_values is specified. If no throttler name is specified, all throttlers will be updated. + +#### Example + +
    UpdateThrottlerConfiguration `-server <vtworker or vttablet> [-copy_zero_values] "<configuration protobuf text>" [<throttler name>]`
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| copy_zero_values | Boolean | If true, fields with zero values will be copied as well | +| server | string | vtworker or vttablet to connect to | + + +#### Arguments + +* <vtworker or vttablet> – Required. +* <throttler name> – Optional. + +#### Errors + +* Failed to unmarshal the configuration protobuf text (%v) into a protobuf instance: %v +* error creating a throttler client for <server> '%v': %v +* failed to update the throttler configuration on <server> '%v': %v + + +## Schema, Version, Permissions + +* [ApplySchema](#applyschema) +* [ApplyVSchema](#applyvschema) +* [CopySchemaShard](#copyschemashard) +* [GetPermissions](#getpermissions) +* [GetSchema](#getschema) +* [GetVSchema](#getvschema) +* [RebuildVSchemaGraph](#rebuildvschemagraph) +* [ReloadSchema](#reloadschema) +* [ReloadSchemaKeyspace](#reloadschemakeyspace) +* [ReloadSchemaShard](#reloadschemashard) +* [ValidatePermissionsKeyspace](#validatepermissionskeyspace) +* [ValidatePermissionsShard](#validatepermissionsshard) +* [ValidateSchemaKeyspace](#validateschemakeyspace) +* [ValidateSchemaShard](#validateschemashard) +* [ValidateVersionKeyspace](#validateversionkeyspace) +* [ValidateVersionShard](#validateversionshard) + +### ApplySchema + +Applies the schema change to the specified keyspace on every master, running in parallel on all shards. The changes are then propagated to slaves via replication. + +#### Example + +
    ApplySchema [-wait_replicas_timeout=10s] {-sql=<sql> || -sql-file=<filename>} <keyspace>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| sql | string | A list of semicolon-delimited SQL commands | +| sql-file | string | Identifies the file that contains the SQL commands | +| wait_replicas_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the command<ApplySchema> command This error occurs if the command is not called with exactly one argument. + + +### ApplyVSchema + +Applies the VTGate routing schema to the provided keyspace. Shows the result after application. + +#### Example + +
    ApplyVSchema {-vschema=<vschema> || -vschema_file=<vschema file>} [-cells=c1,c2,...] [-skip_rebuild] <keyspace>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | If specified, limits the rebuild to the cells, after upload. Ignored if skipRebuild is set. | +| skip_rebuild | Boolean | If set, do no rebuild the SrvSchema objects. | +| vschema | string | Identifies the VTGate routing schema | +| vschema_file | string | Identifies the VTGate routing schema file | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the <ApplyVSchema> command This error occurs if the command is not called with exactly one argument. +* either the <vschema> or <vschema>File flag must be specified when calling the <ApplyVSchema> command + + +### CopySchemaShard + +Copies the schema from a source shard's master (or a specific tablet) to a destination shard. The schema is applied directly on the master of the destination shard, and it is propagated to the replicas through binlogs. + +#### Example + +
    CopySchemaShard [-tables=<table1>,<table2>,...] [-exclude_tables=<table1>,<table2>,...] [-include-views] [-wait_replicas_timeout=10s] {<source keyspace/shard> || <source tablet alias>} <destination keyspace/shard>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the output | +| tables | string | Specifies a comma-separated list of tables to copy. Each is either an exact match, or a regular expression of the form /regexp/ | +| wait_replicas_timeout | Duration | The amount of time to wait for slaves to receive the schema change via replication. | + + +#### Arguments + +* <source tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <destination keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <source keyspace/shard> and <destination keyspace/shard> arguments are both required for the <CopySchemaShard> command. Instead of the <source keyspace/shard> argument, you can also specify <tablet alias> which refers to a specific tablet of the shard in the source keyspace This error occurs if the command is not called with exactly 2 arguments. + + +### GetPermissions + +Displays the permissions for a tablet. + +#### Example + +
    GetPermissions <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <GetPermissions> command This error occurs if the command is not called with exactly one argument. + + +### GetSchema + +Displays the full schema for a tablet, or just the schema for the specified tables in that tablet. + +#### Example + +
    GetSchema [-tables=<table1>,<table2>,...] [-exclude_tables=<table1>,<table2>,...] [-include-views] <tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the output | +| table_names_only | Boolean | Only displays table names that match | +| tables | string | Specifies a comma-separated list of tables for which we should gather information. Each is either an exact match, or a regular expression of the form /regexp/ | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <GetSchema> command This error occurs if the command is not called with exactly one argument. + + +### GetVSchema + +Displays the VTGate routing schema. + +#### Example + +
    GetVSchema <keyspace>
    + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the <GetVSchema> command This error occurs if the command is not called with exactly one argument. + + +### RebuildVSchemaGraph + +Rebuilds the cell-specific SrvVSchema from the global VSchema objects in the provided cells (or all cells if none provided). + +#### Example + +
    RebuildVSchemaGraph [-cells=c1,c2,...]
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to look for tablets | + + +#### Errors + +* <RebuildVSchemaGraph> doesn't take any arguments This error occurs if the command is not called with exactly 0 arguments. + + +### ReloadSchema + +Reloads the schema on a remote tablet. + +#### Example + +
    ReloadSchema <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <ReloadSchema> command This error occurs if the command is not called with exactly one argument. + + +### ReloadSchemaKeyspace + +Reloads the schema on all the tablets in a keyspace. + +#### Example + +
    ReloadSchemaKeyspace [-concurrency=10] [-include_master=false] <keyspace>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | How many tablets to reload in parallel | +| include_master | Boolean | Include the master tablet(s) | + + +#### Arguments + +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace> argument is required for the <ReloadSchemaKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### ReloadSchemaShard + +Reloads the schema on all the tablets in a shard. + +#### Example + +
    ReloadSchemaShard [-concurrency=10] [-include_master=false] <keyspace/shard>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | How many tablets to reload in parallel | +| include_master | Boolean | Include the master tablet | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ReloadSchemaShard> command This error occurs if the command is not called with exactly one argument. + + +### ValidatePermissionsKeyspace + +Validates that the master permissions from shard 0 match those of all of the other tablets in the keyspace. + +#### Example + +
    ValidatePermissionsKeyspace <keyspace name>
    + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace name> argument is required for the <ValidatePermissionsKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### ValidatePermissionsShard + +Validates that the master permissions match all the slaves. + +#### Example + +
    ValidatePermissionsShard <keyspace/shard>
    + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ValidatePermissionsShard> command This error occurs if the command is not called with exactly one argument. + + +### ValidateSchemaKeyspace + +Validates that the master schema from shard 0 matches the schema on all of the other tablets in the keyspace. + +#### Example + +
    ValidateSchemaKeyspace [-exclude_tables=''] [-include-views] <keyspace name>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the validation | + + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace name> argument is required for the <ValidateSchemaKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### ValidateSchemaShard + +Validates that the master schema matches all of the slaves. + +#### Example + +
    ValidateSchemaShard [-exclude_tables=''] [-include-views] <keyspace/shard>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| exclude_tables | string | Specifies a comma-separated list of tables to exclude. Each is either an exact match, or a regular expression of the form /regexp/ | +| include-views | Boolean | Includes views in the validation | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ValidateSchemaShard> command This error occurs if the command is not called with exactly one argument. + + +### ValidateVersionKeyspace + +Validates that the master version from shard 0 matches all of the other tablets in the keyspace. + +#### Example + +
    ValidateVersionKeyspace <keyspace name>
    + +#### Arguments + +* <keyspace name> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <keyspace name> argument is required for the <ValidateVersionKeyspace> command This error occurs if the command is not called with exactly one argument. + + +### ValidateVersionShard + +Validates that the master version matches all of the slaves. + +#### Example + +
    ValidateVersionShard <keyspace/shard>
    + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ValidateVersionShard> command This error occurs if the command is not called with exactly one argument. + + +## Serving Graph + +* [GetSrvKeyspace](#getsrvkeyspace) +* [GetSrvKeyspaceNames](#getsrvkeyspacenames) +* [GetSrvVSchema](#getsrvvschema) + +### GetSrvKeyspace + +Outputs a JSON structure that contains information about the SrvKeyspace. + +#### Example + +
    GetSrvKeyspace <cell> <keyspace>
    + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <keyspace> – Required. The name of a sharded database that contains one or more tables. Vitess distributes keyspace shards into multiple machines and provides an SQL interface to query the data. The argument value must be a string that does not contain whitespace. + +#### Errors + +* the <cell> and <keyspace> arguments are required for the <GetSrvKeyspace> command This error occurs if the command is not called with exactly 2 arguments. + + +### GetSrvKeyspaceNames + +Outputs a list of keyspace names. + +#### Example + +
    GetSrvKeyspaceNames <cell>
    + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <GetSrvKeyspaceNames> command This error occurs if the command is not called with exactly one argument. + + +### GetSrvVSchema + +Outputs a JSON structure that contains information about the SrvVSchema. + +#### Example + +
    GetSrvVSchema <cell>
    + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <cell> argument is required for the <GetSrvVSchema> command This error occurs if the command is not called with exactly one argument. + + +## Shards + +* [CreateShard](#createshard) +* [DeleteShard](#deleteshard) +* [EmergencyReparentShard](#emergencyreparentshard) +* [GetShard](#getshard) +* [InitShardMaster](#initshardmaster) +* [ListBackups](#listbackups) +* [ListShardTablets](#listshardtablets) +* [PlannedReparentShard](#plannedreparentshard) +* [RemoveBackup](#removebackup) +* [RemoveShardCell](#removeshardcell) +* [SetShardServedTypes](#setshardservedtypes) +* [SetShardTabletControl](#setshardtabletcontrol) +* [ShardReplicationFix](#shardreplicationfix) +* [ShardReplicationPositions](#shardreplicationpositions) +* [SourceShardAdd](#sourceshardadd) +* [SourceShardDelete](#sourcesharddelete) +* [TabletExternallyReparented](#tabletexternallyreparented) +* [ValidateShard](#validateshard) +* [WaitForFilteredReplication](#waitforfilteredreplication) + +### CreateShard + +Creates the specified shard. + +#### Example + +
    CreateShard [-force] [-parent] <keyspace/shard>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds with the command even if the keyspace already exists | +| parent | Boolean | Creates the parent keyspace if it doesn't already exist | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <CreateShard> command This error occurs if the command is not called with exactly one argument. + + +### DeleteShard + +Deletes the specified shard(s). In recursive mode, it also deletes all tablets belonging to the shard. Otherwise, there must be no tablets left in the shard. + +#### Example + +
    DeleteShard [-recursive] [-even_if_serving] <keyspace/shard> ...
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| even_if_serving | Boolean | Remove the shard even if it is serving. Use with caution. | +| recursive | Boolean | Also delete all tablets belonging to the shard. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <keyspace/shard> argument must be used to identify at least one keyspace and shard when calling the <DeleteShard> command This error occurs if the command is not called with at least one argument. + + +### EmergencyReparentShard + +Reparents the shard to the new master. Assumes the old master is dead and not responding. + +#### Example + +
    EmergencyReparentShard -keyspace_shard=<keyspace/shard> -new_master=<tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | +| new_master | string | alias of a tablet that should be the new master | +| wait_replicas_timeout | Duration | time to wait for slaves to catch up in reparenting | + + +#### Errors + +* action <EmergencyReparentShard> requires -keyspace_shard=<keyspace/shard> -new_master=<tablet alias> This error occurs if the command is not called with exactly 0 arguments. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) +* cannot use legacy syntax and flag -<new_master> for action <EmergencyReparentShard> at the same time + + +### GetShard + +Outputs a JSON structure that contains information about the Shard. + +#### Example + +
    GetShard <keyspace/shard>
    + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <GetShard> command This error occurs if the command is not called with exactly one argument. + + +### InitShardMaster + +Sets the initial master for a shard. Will make all other tablets in the shard slaves of the provided master. WARNING: this could cause data loss on an already replicating shard. PlannedReparentShard or EmergencyReparentShard should be used instead. + +#### Example + +
    InitShardMaster [-force] [-wait_replicas_timeout=<duration>] <keyspace/shard> <tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | will force the reparent even if the provided tablet is not a master or the shard master | +| wait_replicas_timeout | Duration | time to wait for slaves to catch up in reparenting | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <InitShardMaster> requires <keyspace/shard> <tablet alias> This error occurs if the command is not called with exactly 2 arguments. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) + + +### ListBackups + +Lists all the backups for a shard. + +#### Example + +
    ListBackups <keyspace/shard>
    + +#### Errors + +* action <ListBackups> requires <keyspace/shard> This error occurs if the command is not called with exactly one argument. + + +### ListShardTablets + +Lists all tablets in the specified shard. + +#### Example + +
    ListShardTablets <keyspace/shard>
    + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ListShardTablets> command This error occurs if the command is not called with exactly one argument. + + +### PlannedReparentShard + +Reparents the shard to the new master, or away from old master. Both old and new master need to be up and running. + +#### Example + +
    PlannedReparentShard -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>]
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| avoid_master | string | alias of a tablet that should not be the master, i.e. reparent to any other tablet if this one is the master | +| keyspace_shard | string | keyspace/shard of the shard that needs to be reparented | +| new_master | string | alias of a tablet that should be the new master | +| wait_replicas_timeout | Duration | time to wait for slaves to catch up in reparenting | + + +#### Errors + +* action <PlannedReparentShard> requires -keyspace_shard=<keyspace/shard> [-new_master=<tablet alias>] [-avoid_master=<tablet alias>] This error occurs if the command is not called with exactly 0 arguments. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) +* cannot use legacy syntax and flags -<keyspace_shard> and -<new_master> for action <PlannedReparentShard> at the same time + + +### RemoveBackup + +Removes a backup for the BackupStorage. + +#### Example + +
    RemoveBackup <keyspace/shard> <backup name>
    + +#### Arguments + +* <backup name> – Required. + +#### Errors + +* action <RemoveBackup> requires <keyspace/shard> <backup name> This error occurs if the command is not called with exactly 2 arguments. + + +### RemoveShardCell + +Removes the cell from the shard's Cells list. + +#### Example + +
    RemoveShardCell [-force] [-recursive] <keyspace/shard> <cell>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| force | Boolean | Proceeds even if the cell's topology server cannot be reached. The assumption is that you turned down the entire cell, and just need to update the global topo data. | +| recursive | Boolean | Also delete all tablets in that cell belonging to the specified shard. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. + +#### Errors + +* the <keyspace/shard> and <cell> arguments are required for the <RemoveShardCell> command This error occurs if the command is not called with exactly 2 arguments. + + +### SetShardServedTypes + +Add or remove served type to/from a shard. This is meant as an emergency function. It does not rebuild any serving graph i.e. does not run 'RebuildKeyspaceGraph'. + +#### Example + +
    SetShardServedTypes [--cells=c1,c2,...] [--remove] <keyspace/shard> <served tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells to update | +| remove | Boolean | Removes the served tablet type | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <served tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <keyspace/shard> and <served tablet type> arguments are both required for the <SetShardServedTypes> command This error occurs if the command is not called with exactly 2 arguments. + + +### SetShardTabletControl + +Sets the TabletControl record for a shard and type. Only use this for an emergency fix or after a finished vertical split. The *MigrateServedFrom* and *MigrateServedType* commands set this field appropriately already. Always specify the blacklisted_tables flag for vertical splits, but never for horizontal splits.

    To set the DisableQueryServiceFlag, keep 'blacklisted_tables' empty, and set 'disable_query_service' to true or false. Useful to fix horizontal splits gone wrong.

    To change the blacklisted tables list, specify the 'blacklisted_tables' parameter with the new list. Useful to fix tables that are being blocked after a vertical split.

    To just remove the ShardTabletControl entirely, use the 'remove' flag, useful after a vertical split is finished to remove serving restrictions. + +#### Example + +
    SetShardTabletControl [--cells=c1,c2,...] [--blacklisted_tables=t1,t2,...] [--remove] [--disable_query_service] <keyspace/shard> <tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| blacklisted_tables | string | Specifies a comma-separated list of tables to blacklist (used for vertical split). Each is either an exact match, or a regular expression of the form '/regexp/'. | +| cells | string | Specifies a comma-separated list of cells to update | +| disable_query_service | Boolean | Disables query service on the provided nodes. This flag requires 'blacklisted_tables' and 'remove' to be unset, otherwise it's ignored. | +| remove | Boolean | Removes cells for vertical splits. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <keyspace/shard> and <tablet type> arguments are both required for the <SetShardTabletControl> command This error occurs if the command is not called with exactly 2 arguments. + + +### ShardReplicationFix + +Walks through a ShardReplication object and fixes the first error that it encounters. + +#### Example + +
    ShardReplicationFix <cell> <keyspace/shard>
    + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <cell> and <keyspace/shard> arguments are required for the ShardReplicationRemove command This error occurs if the command is not called with exactly 2 arguments. + + +### ShardReplicationPositions + +Shows the replication status of each slave machine in the shard graph. In this case, the status refers to the replication lag between the master vttablet and the slave vttablet. In Vitess, data is always written to the master vttablet first and then replicated to all slave vttablets. Output is sorted by tablet type, then replication position. Use ctrl-C to interrupt command and see partial result if needed. + +#### Example + +
    ShardReplicationPositions <keyspace/shard>
    + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ShardReplicationPositions> command This error occurs if the command is not called with exactly one argument. + + +### SourceShardAdd + +Adds the SourceShard record with the provided index. This is meant as an emergency function. It does not call RefreshState for the shard master. + +#### Example + +
    SourceShardAdd [--key_range=<keyrange>] [--tables=<table1,table2,...>] <keyspace/shard> <uid> <source keyspace/shard>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| key_range | string | Identifies the key range to use for the SourceShard | +| tables | string | Specifies a comma-separated list of tables to replicate (used for vertical split). Each is either an exact match, or a regular expression of the form /regexp/ | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <uid> – Required. +* <source keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard>, <uid>, and <source keyspace/shard> arguments are all required for the <SourceShardAdd> command This error occurs if the command is not called with exactly 3 arguments. + + +### SourceShardDelete + +Deletes the SourceShard record with the provided index. This is meant as an emergency cleanup function. It does not call RefreshState for the shard master. + +#### Example + +
    SourceShardDelete <keyspace/shard> <uid>
    + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. +* <uid> – Required. + +#### Errors + +* the <keyspace/shard> and <uid> arguments are both required for the <SourceShardDelete> command This error occurs if the command is not called with at least 2 arguments. + + +### TabletExternallyReparented + +Changes metadata in the topology server to acknowledge a shard master change performed by an external tool. See the Reparenting guide for more information:https://github.com/vitessio/vitess/blob/master/doc/Reparenting.md#external-reparents. + +#### Example + +
    TabletExternallyReparented <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <TabletExternallyReparented> command This error occurs if the command is not called with exactly one argument. + + +### ValidateShard + +Validates that all nodes that are reachable from this shard are consistent. + +#### Example + +
    ValidateShard [-ping-tablets] <keyspace/shard>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| ping-tablets | Boolean | Indicates whether all tablets should be pinged during the validation process | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <ValidateShard> command This error occurs if the command is not called with exactly one argument. + + +### WaitForFilteredReplication + +Blocks until the specified shard has caught up with the filtered replication of its source shard. + +#### Example + +
    WaitForFilteredReplication [-max_delay <max_delay, default 30s>] <keyspace/shard>
    + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <WaitForFilteredReplication> command This error occurs if the command is not called with exactly one argument. + + +## Tablets + +* [Backup](#backup) +* [ChangeSlaveType](#changeslavetype) +* [DeleteTablet](#deletetablet) +* [ExecuteFetchAsDba](#executefetchasdba) +* [ExecuteHook](#executehook) +* [GetTablet](#gettablet) +* [IgnoreHealthError](#ignorehealtherror) +* [InitTablet](#inittablet) +* [Ping](#ping) +* [RefreshState](#refreshstate) +* [RefreshStateByShard](#refreshstatebyshard) +* [ReparentTablet](#reparenttablet) +* [RestoreFromBackup](#restorefrombackup) +* [RunHealthCheck](#runhealthcheck) +* [SetReadOnly](#setreadonly) +* [SetReadWrite](#setreadwrite) +* [Sleep](#sleep) +* [StartSlave](#startslave) +* [StopSlave](#stopslave) +* [UpdateTabletAddrs](#updatetabletaddrs) + +### Backup + +Stops mysqld and uses the BackupStorage service to store a new backup. This function also remembers if the tablet was replicating so that it can restore the same state after the backup completes. + +#### Example + +
    Backup [-concurrency=4] <tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| concurrency | Int | Specifies the number of compression/checksum jobs to run simultaneously | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <Backup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. + + +### ChangeSlaveType + +Changes the db type for the specified tablet, if possible. This command is used primarily to arrange replicas, and it will not convert a master.

    NOTE: This command automatically updates the serving graph.

    + +#### Example + +
    ChangeSlaveType [-dry-run] <tablet alias> <tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| dry-run | Boolean | Lists the proposed change without actually executing it | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <tablet alias> and <db type> arguments are required for the <ChangeSlaveType> command This error occurs if the command is not called with exactly 2 arguments. +* failed reading tablet %v: %v +* invalid type transition %v: %v -> %v + + +### DeleteTablet + +Deletes tablet(s) from the topology. + +#### Example + +
    DeleteTablet [-allow_master] <tablet alias> ...
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| allow_master | Boolean | Allows for the master tablet of a shard to be deleted. Use with caution. | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. To specify multiple values for this argument, separate individual values with a space. + +#### Errors + +* the <tablet alias> argument must be used to specify at least one tablet when calling the <DeleteTablet> command This error occurs if the command is not called with at least one argument. + + +### ExecuteFetchAsDba + +Runs the given SQL command as a DBA on the remote tablet. + +#### Example + +
    ExecuteFetchAsDba [-max_rows=10000] [-disable_binlogs] [-json] <tablet alias> <sql command>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| disable_binlogs | Boolean | Disables writing to binlogs during the query | +| json | Boolean | Output JSON instead of human-readable table | +| max_rows | Int | Specifies the maximum number of rows to allow in reset | +| reload_schema | Boolean | Indicates whether the tablet schema will be reloaded after executing the SQL command. The default value is false, which indicates that the tablet schema will not be reloaded. | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <sql command> – Required. + +#### Errors + +* the <tablet alias> and <sql command> arguments are required for the <ExecuteFetchAsDba> command This error occurs if the command is not called with exactly 2 arguments. + + +### ExecuteHook + +Runs the specified hook on the given tablet. A hook is a script that resides in the $VTROOT/vthook directory. You can put any script into that directory and use this command to run that script.

    For this command, the param=value arguments are parameters that the command passes to the specified hook. + +#### Example + +
    ExecuteHook <tablet alias> <hook name> [<param1=value1> <param2=value2> ...]
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <hook name> – Required. +* <param1=value1> <param2=value2> . – Optional. + +#### Errors + +* the <tablet alias> and <hook name> arguments are required for the <ExecuteHook> command This error occurs if the command is not called with at least 2 arguments. + + +### GetTablet + +Outputs a JSON structure that contains information about the Tablet. + +#### Example + +
    GetTablet <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <GetTablet> command This error occurs if the command is not called with exactly one argument. + + +### IgnoreHealthError + +Sets the regexp for health check errors to ignore on the specified tablet. The pattern has implicit ^$ anchors. Set to empty string or restart vttablet to stop ignoring anything. + +#### Example + +
    IgnoreHealthError <tablet alias> <ignore regexp>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <ignore regexp> – Required. + +#### Errors + +* the <tablet alias> and <ignore regexp> arguments are required for the <IgnoreHealthError> command This error occurs if the command is not called with exactly 2 arguments. + + +### InitTablet + +Initializes a tablet in the topology.

    + +#### Example + +
    InitTablet [-allow_update] [-allow_different_shard] [-allow_master_override] [-parent] [-db_name_override=<db name>] [-hostname=<hostname>] [-mysql_port=<port>] [-port=<port>] [-grpc_port=<port>] -keyspace=<keyspace> -shard=<shard> <tablet alias> <tablet type>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| allow_master_override | Boolean | Use this flag to force initialization if a tablet is created as master, and a master for the keyspace/shard already exists. Use with caution. | +| allow_update | Boolean | Use this flag to force initialization if a tablet with the same name already exists. Use with caution. | +| db_name_override | string | Overrides the name of the database that the vttablet uses | +| grpc_port | Int | The gRPC port for the vttablet process | +| hostname | string | The server on which the tablet is running | +| keyspace | string | The keyspace to which this tablet belongs | +| mysql_host | string | The mysql host for the mysql server | +| mysql_port | Int | The mysql port for the mysql server | +| parent | Boolean | Creates the parent shard and keyspace if they don't yet exist | +| port | Int | The main port for the vttablet process | +| shard | string | The shard to which this tablet belongs | +| tags | string | A comma-separated list of key:value pairs that are used to tag the tablet | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <tablet type> – Required. The vttablet's role. Valid values are: + + * backup – A slaved copy of data that is offline to queries other than for backup purposes + * batch – A slaved copy of data for OLAP load patterns (typically for MapReduce jobs) + * drained – A tablet that is reserved for a background process. For example, a tablet used by a vtworker process, where the tablet is likely lagging in replication. + * experimental – A slaved copy of data that is ready but not serving query traffic. The value indicates a special characteristic of the tablet that indicates the tablet should not be considered a potential master. Vitess also does not worry about lag for experimental tablets when reparenting. + * master – A primary copy of data + * rdonly – A slaved copy of data for OLAP load patterns + * replica – A slaved copy of data ready to be promoted to master + * restore – A tablet that is restoring from a snapshot. Typically, this happens at tablet startup, then it goes to its right state. + * schema_apply – A slaved copy of data that had been serving query traffic but that is now applying a schema change. Following the change, the tablet will revert to its serving type. + * snapshot_source – A slaved copy of data where mysqld is not running and where Vitess is serving data files to clone slaves. Use this command to enter this mode: 
    vtctl Snapshot -server-mode ...
    Use this command to exit this mode: 
    vtctl SnapshotSourceEnd ...
    + * spare – A slaved copy of data that is ready but not serving query traffic. The data could be a potential master tablet. + + + + +#### Errors + +* the <tablet alias> and <tablet type> arguments are both required for the <InitTablet> command This error occurs if the command is not called with exactly 2 arguments. + + +### Ping + +Checks that the specified tablet is awake and responding to RPCs. This command can be blocked by other in-flight operations. + +#### Example + +
    Ping <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <Ping> command This error occurs if the command is not called with exactly one argument. + + +### RefreshState + +Reloads the tablet record on the specified tablet. + +#### Example + +
    RefreshState <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <RefreshState> command This error occurs if the command is not called with exactly one argument. + + +### RefreshStateByShard + +Runs 'RefreshState' on all tablets in the given shard. + +#### Example + +
    RefreshStateByShard [-cells=c1,c2,...] <keyspace/shard>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cells | string | Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered. | + + +#### Arguments + +* <keyspace/shard> – Required. The name of a sharded database that contains one or more tables as well as the shard associated with the command. The keyspace must be identified by a string that does not contain whitespace, while the shard is typically identified by a string in the format <range start>-<range end>. + +#### Errors + +* the <keyspace/shard> argument is required for the <RefreshStateByShard> command This error occurs if the command is not called with exactly one argument. + + +### ReparentTablet + +Reparent a tablet to the current master in the shard. This only works if the current slave position matches the last known reparent action. + +#### Example + +
    ReparentTablet <tablet alias>
    + +#### Errors + +* action <ReparentTablet> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* active reparent commands disabled (unset the -disable_active_reparents flag to enable) + + +### RestoreFromBackup + +Stops mysqld and restores the data from the latest backup. + +#### Example + +
    RestoreFromBackup <tablet alias>
    + +#### Errors + +* the <RestoreFromBackup> command requires the <tablet alias> argument This error occurs if the command is not called with exactly one argument. + + +### RunHealthCheck + +Runs a health check on a remote tablet. + +#### Example + +
    RunHealthCheck <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <RunHealthCheck> command This error occurs if the command is not called with exactly one argument. + + +### SetReadOnly + +Sets the tablet as read-only. + +#### Example + +
    SetReadOnly <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <SetReadOnly> command This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + + +### SetReadWrite + +Sets the tablet as read-write. + +#### Example + +
    SetReadWrite <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <SetReadWrite> command This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + + +### Sleep + +Blocks the action queue on the specified tablet for the specified amount of time. This is typically used for testing. + +#### Example + +
    Sleep <tablet alias> <duration>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. +* <duration> – Required. The amount of time that the action queue should be blocked. The value is a string that contains a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "1h45m". See the definition of the Go language's ParseDuration function for more details. Note that, in practice, the value should be a positively signed value. + +#### Errors + +* the <tablet alias> and <duration> arguments are required for the <Sleep> command This error occurs if the command is not called with exactly 2 arguments. + + +### StartSlave + +Starts replication on the specified slave. + +#### Example + +
    StartSlave <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <StartSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + + +### StopSlave + +Stops replication on the specified slave. + +#### Example + +
    StopSlave <tablet alias>
    + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* action <StopSlave> requires <tablet alias> This error occurs if the command is not called with exactly one argument. +* failed reading tablet %v: %v + + +### UpdateTabletAddrs + +Updates the IP address and port numbers of a tablet. + +#### Example + +
    UpdateTabletAddrs [-hostname <hostname>] [-ip-addr <ip addr>] [-mysql-port <mysql port>] [-vt-port <vt port>] [-grpc-port <grpc port>] <tablet alias>
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| grpc-port | Int | The gRPC port for the vttablet process | +| hostname | string | The fully qualified host name of the server on which the tablet is running. | +| mysql-port | Int | The mysql port for the mysql daemon | +| mysql_host | string | The mysql host for the mysql server | +| vt-port | Int | The main port for the vttablet process | + + +#### Arguments + +* <tablet alias> – Required. A Tablet Alias uniquely identifies a vttablet. The argument value is in the format <cell name>-<uid>. + +#### Errors + +* the <tablet alias> argument is required for the <UpdateTabletAddrs> command This error occurs if the command is not called with exactly one argument. + + +## Topo + +* [TopoCat](#topocat) + +### TopoCat + +Retrieves the file(s) at <path> from the topo service, and displays it. It can resolve wildcards, and decode the proto-encoded data. + +#### Example + +
    TopoCat [-cell <cell>] [-decode_proto] [-long] <path> [<path>...]
    + +#### Flags + +| Name | Type | Definition | +| :-------- | :--------- | :--------- | +| cell | string | topology cell to cat the file from. Defaults to global cell. | +| decode_proto | Boolean | decode proto files and display them as text | +| long | Boolean | long listing. | + + +#### Arguments + +* <cell> – Required. A cell is a location for a service. Generally, a cell resides in only one cluster. In Vitess, the terms "cell" and "data center" are interchangeable. The argument value is a string that does not contain whitespace. +* <path> – Required. +* <path>. – Optional. + +#### Errors + +* <TopoCat>: no path specified This error occurs if the command is not called with at least one argument. +* <TopoCat>: invalid wildcards: %v +* <TopoCat>: some paths had errors diff --git a/content/zh/docs/19.0/schema-management/_index.md b/content/zh/docs/19.0/schema-management/_index.md new file mode 100644 index 000000000..d4b4aa4e4 --- /dev/null +++ b/content/zh/docs/19.0/schema-management/_index.md @@ -0,0 +1,138 @@ +--- +title: Schema Management +description: More information about all things schema and VSchema +weight: 6 +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} + +Using Vitess requires you to work with two different types of schemas: + +1. The MySQL database schema. This is the schema of the individual MySQL instances. +2. The [VSchema](../schema-management/vschema), which describes all the keyspaces and how they're sharded. + +The workflow for the `VSchema` is as follows: + +1. Apply the `VSchema` for each keyspace using the `ApplyVschema` command. This saves the VSchemas in the global topo server. +2. Execute `RebuildVSchemaGraph` for each cell (or all cells). This command propagates a denormalized version of the combined VSchema to all the specified cells. The main purpose for this propagation is to minimize the dependency of each cell from the global topology. The ability to push a change to only specific cells allows you to canary the change to make sure that it's good before deploying it everywhere. + +This document describes the [`vtctl`](../reference/vtctl/) commands that you can use to [review](#reviewing-your-schema) or [update](#changing-your-schema) your schema in Vitess. + +Note that this functionality is not recommended for long-running schema changes. It is recommended to use a tool such as [`pt-online-schema-change`](https://www.percona.com/doc/percona-toolkit/LATEST/pt-online-schema-change.html) or [`gh-ost`](https://github.com/github/gh-ost) instead. + + +## Reviewing your schema + +This section describes the following vtctl commands, which let you look at the schema and validate its consistency across tablets or shards: + +* [GetSchema](#getschema) +* [ValidateSchemaShard](#validateschemashard) +* [ValidateSchemaKeyspace](#validateschemakeyspace) +* [GetVSchema](#getvschema) +* [GetSrvVSchema](#getsrvvschema) + +### GetSchema + +The [GetSchema](../reference/vtctl/#getschema) command displays the full schema for a tablet or a subset of the tablet's tables. When you call `GetSchema`, you specify the tablet alias that uniquely identifies the tablet. The `` argument value has the format `-`. + +**Note**: You can use the [`vtctl ListAllTablets`](../reference/vtctl/#listalltablets) command to retrieve a list of tablets in a cell and their unique IDs. + +The following example retrieves the schema for the tablet with the unique ID test-000000100: + +``` sh +GetSchema test-000000100 +``` + +### ValidateSchemaShard + +The [`ValidateSchemaShard`](../reference/vtctl/#validateschemashard) command confirms that for a given keyspace, all of the slave tablets in a specified shard have the same schema as the master tablet in that shard. When you call `ValidateSchemaShard`, you specify both the keyspace and the shard that you are validating. + +The following command confirms that the master and slave tablets in shard `0` all have the same schema for the `user` keyspace: + +``` sh +ValidateSchemaShard user/0 +``` + +### ValidateSchemaKeyspace + +The [`ValidateSchemaKeyspace`](../reference/vtctl/#validateschemakeyspace) command confirms that all of the tablets in a given keyspace have the the same schema as the master tablet on shard `0` in that keyspace. Thus, whereas the `ValidateSchemaShard` command confirms the consistency of the schema on tablets within a shard for a given keyspace, `ValidateSchemaKeyspace` confirms the consistency across all tablets in all shards for that keyspace. + +The following command confirms that all tablets in all shards have the same schema as the master tablet in shard 0 for the user keyspace: + +``` sh +ValidateSchemaKeyspace user +``` + +### GetVSchema + +The [`GetVSchema`](../reference/vtctl/#getvschema) command displays the global VSchema for the specified keyspace. + +### GetSrvVSchema + +The [`GetSrvVSchema`](../reference/vtctl/#getsrvvschema) command displays the combined VSchema for a given cell. + +## Changing your schema + +This section describes the following commands: + +* [ApplySchema](#applyschema) +* [ApplyVSchema](#applyvschema) +* [RebuildVSchemaGraph](#rebuildvschemagraph) + +### ApplySchema + +Vitess' schema modification functionality is designed the following goals in mind: + +* Enable simple updates that propagate to your entire fleet of servers. +* Require minimal human interaction. +* Minimize errors by testing changes against a temporary database. +* Guarantee very little downtime (or no downtime) for most schema updates. +* Do not store permanent schema data in the topology server. + +Note that, at this time, Vitess only supports [data definition statements](https://dev.mysql.com/doc/refman/5.6/en/sql-data-definition-statements.html) that create, modify, or delete database tables. For instance, `ApplySchema` does not affect stored procedures or grants. + +The [ApplySchema](../reference/vtctl/#applyvschema) command applies a schema change to the specified keyspace on every master tablet, running in parallel on all shards. Changes are then propagated to slaves via replication. The command format is: `ApplySchema {-sql= || -sql_file=} ` + +When the `ApplySchema` action actually applies a schema change to the specified keyspace, it performs the following steps: + +1. It finds shards that belong to the keyspace, including newly added shards if a [resharding event](../sharding/#resharding) has taken place. +2. It validates the SQL syntax and determines the impact of the schema change. If the scope of the change is too large, Vitess rejects it. See the [permitted schema changes](#permitted-schema-changes) section for more detail. +3. It employs a pre-flight check to ensure that a schema update will succeed before the change is actually applied to the live database. In this stage, Vitess copies the current schema into a temporary database, applies the change there to validate it, and retrieves the resulting schema. By doing so, Vitess verifies that the change succeeds without actually touching live database tables. +4. It applies the SQL command on the master tablet in each shard. + +The following sample command applies the SQL in the **user_table.sql** file to the **user** keyspace: + +`ApplySchema -sql_file=user_table.sql user` + +#### Permitted schema changes + +The `ApplySchema` command supports a limited set of DDL statements. In addition, Vitess rejects some schema changes because large changes can slow replication and may reduce the availability of your overall system. + +The following list identifies types of DDL statements that Vitess supports: + +* `CREATE TABLE` +* `CREATE INDEX` +* `CREATE VIEW` +* `ALTER TABLE` +* `ALTER VIEW` +* `RENAME TABLE` +* `DROP TABLE` +* `DROP INDEX` +* `DROP VIEW` + +In addition, Vitess applies the following rules when assessing the impact of a potential change: + +* `DROP` statements are always allowed, regardless of the table's size. +* `ALTER` statements are only allowed if the table on the shard's master tablet has 100,000 rows or less. +* For all other statements, the table on the shard's master tablet must have 2 million rows or less. + +If a schema change gets rejected because it affects too many rows, you can specify the flag `-allow_long_unavailability` to tell `ApplySchema` to skip this check. However, we do not recommend this. Instead, you should apply large schema changes by following the [schema swap](../schema-management/schema-swap) process. + +### ApplyVSchema + +The [`ApplyVSchema`](../reference/vtctl/#applyvschema) command applies the specified VSchema to the keyspace. The VSchema can be specified as a string or in a file. + +### RebuildVSchemaGraph + +The [`RebuildVSchemaGraph`](../reference/vtctl/#rebuildvschemagraph) command propagates the global VSchema to a specific cell or the list of specified cells. diff --git a/content/zh/docs/19.0/schema-management/consistent-lookup.md b/content/zh/docs/19.0/schema-management/consistent-lookup.md new file mode 100644 index 000000000..30f949874 --- /dev/null +++ b/content/zh/docs/19.0/schema-management/consistent-lookup.md @@ -0,0 +1,33 @@ +--- +title: Consistent Lookup Vindexes +weight: 3 +--- + +As mentioned in the VSchema section, Vitess supports the concept of a lookup vindex, or what is also commonly known as a cross-shard index. It's implemented as a mysql table that maps a column value to the keyspace id. This is usually needed when someone needs to efficiently find a row using a where clause that does not contain the primary vindex. + +This lookup table can be sharded or unsharded. No matter which option one chooses, the lookup row is most likely not going to be in the same shard as the keyspace id it points to. + +Vitess allows the transparent population of these rows by assigning an owner table, which is the main table that requires this lookup. When a row is inserted into the main table, the lookup row for it is created in the lookup table. The lookup row is also deleted on a delete of the main row. These essentially result in distributed transactions, which require 2PC to guarantee atomicity. + +Consistent lookup vindexes use an alternate approach that make use of careful locking and transaction sequences to guarantee consistent, without using 2PC. This gives you the best of both worlds, where you get a consistent cross-shard vindex without paying the price of 2PC. + +## Modified guidance + +The guidance for implementing lookup vindexes has been to create a two-column table. The first column (from column) should match the type of the column of the main table that needs the vindex. The second column (to column) should be a `binary` or a `varbinary` large enough to accommodate the keyspace id. + +This guidance remains the same for unique lookup vindexes. + +For non-unique lookup vindexes, it's recommended that the lookup table consist of multiple columns: The first column continues to be the input for computing the keyspace ids. Beyond this, additional columns are needed to uniquely identify the owner row. This should typically be the primary key of the owner table. But it can be any other column that can be combined with the 'from column' to uniquely identify the owner row. The last column remains the keyspace id like before. + +For example, if a user table had `(user_id, email)`, where `user_id` was the primary key and `email` needed a non-unique lookup vindex, the lookup table would have the following columns `(email, user_id, keyspace_id)`. + +## Lookup vindex types + +There are currently two vindex types for consistent lookup: + +* `consistent_lookup_unique` +* `consistent_lookup` + +An existing `lookup_unique` vindex can be trivially switched to a `consistent_lookup_unique` by changing the vindex type in the VSchema. This is because the data is compatible. + +As for a `lookup`, you can change it to a `consistent_lookup` only if the from columns can uniquely identify the owner row. Without this, many potentially valid inserts would fail. diff --git a/content/zh/docs/19.0/schema-management/mysql-schema.md b/content/zh/docs/19.0/schema-management/mysql-schema.md new file mode 100644 index 000000000..cdd177d66 --- /dev/null +++ b/content/zh/docs/19.0/schema-management/mysql-schema.md @@ -0,0 +1,33 @@ +--- +title: Applying MySQL schema +weight: 1 +--- + +For applying schema changes for MySQL instances managed by Vitess, there are a few options. + +## ApplySchema + +`ApplySchema` is a vtctlclient command that can be used to apply a schema to a keyspace. The main advantage of using this +tool is that it performs some sanity checks about the schema before applying it. For example, if the schema change +affects too many rows of a table, it will reject it. + +However, the down side is that it is a little too strict, and may not work for all use cases. + +## VTGate + +You can send a DDL directly to a VTGate just like you would send to a mysql instance. If the target is a sharded keyspace, +then the DDL would be sprayed to all shards. + +If a specific shard fails you can target it directly using the `keyspace/shard` syntax to retry the apply just to that shard. + +If VTGate does not recognize a DDL syntax, the statement will get rejected. + +This approach is not recommended for changing large tables. + +## Directly to MySQL + +You can apply schema changes directly to MySQL. VTTablet will eventually notice the change and update itself. You can also +explicitly issue the vtctlclient `ReloadSchema` command to make it reload immediately. + +This approach can be extended to use schema deployment tools like `gh-ost` or `pt-online-schema-change`. Using these schema +deployment tools is the recommended approach for large tables, because they incur no downtime. diff --git a/content/zh/docs/19.0/schema-management/routing-rules.md b/content/zh/docs/19.0/schema-management/routing-rules.md new file mode 100644 index 000000000..ca63dc5f4 --- /dev/null +++ b/content/zh/docs/19.0/schema-management/routing-rules.md @@ -0,0 +1,53 @@ +--- +title: Routing Rules +weight: 4 +--- + +The Vitess routing rules feature is a powerful mechanism for directing traffic to the right keyspaces, shards or tablet types. +It fulfils the following use cases: + +* **Routing traffic during resharding**: During resharding, you can specify rules that decide where to send reads and writes. For example, + you can move traffic from the source shard to the destination shards, but only for the `rdonly` or `replica` types. This gives you + the option to try out the new shards and make sure they will work as intended before committing to move the rest of the traffic. + +## ApplyRoutingRules + +You can use the vtctlclient command to apply routing rules: + +``` +ApplyRoutingRules {-rules= || -rules_file=} [-cells=c1,c2,...] [-skip_rebuild] [-dry-run] +``` + +## Syntax + +### Resharding + +Routing rules can be specified using JSON format. Here's an example: + +``` json +{"rules": [ + { + "from_table": "t@rdonly", + "to_tables": ["target.t"] + }, { + "from_table": "target.t", + "to_tables": ["source.t"] + }, { + "from_table": "t", + "to_tables": ["source.t"] + } +]} +``` + +The above JSON specifies the following rules: +* If you sent a query accessing `t` for an `rdonly` instance, then it would be sent to table `t` in the `target` keyspace. +* If you sent a query accessing `target.t` for anything other than `rdonly`, it would be sent `t` in the `source` keyspace. +* If you sent a query accessing `t` without any qualification, it would be sent to `t` in the `source` keyspace. + +These rules are an example of how they can be used to shift traffic for a table during a vertical resharding process. +In this case, the assumption is that we are moving `t` from `source` to `target`, and so far, we've shifted traffic +for just the `rdonly` tablet types. + +By updating these rules, you can eventually move all traffic to `target.t` + +The rules are applied only once. The resulting targets need to specify fully qualified table names. diff --git a/content/zh/docs/19.0/schema-management/vschema.md b/content/zh/docs/19.0/schema-management/vschema.md new file mode 100644 index 000000000..3a2d02fb0 --- /dev/null +++ b/content/zh/docs/19.0/schema-management/vschema.md @@ -0,0 +1,366 @@ +--- +title: VSchema User Guide +weight: 2 +--- + +VSchema stands for Vitess Schema. In contrast to a traditional database schema that contains metadata about tables, a VSchema contains metadata about how tables are organized across keyspaces and shards. Simply put, it contains the information needed to make Vitess look like a single database server. + +For example, the VSchema will contain the information about the sharding key for a sharded table. When the application issues a query with a WHERE clause that references the key, the VSchema information will be used to route the query to the appropriate shard. + +## Sharding Model + +In Vitess, a `keyspace` is sharded by `keyspace ID` ranges. Each row is assigned a keyspace ID, which acts like a street address, and it determines the shard where the row lives. In some respect, one could say that the `keyspace ID` is the equivalent of a NoSQL sharding key. However, there are some differences: + +1. The `keyspace ID` is a concept that is internal to Vitess. The application does not need to know anything about it. +2. There is no physical column that stores the actual `keyspace ID`. This value is computed as needed. + +This difference is significant enough that we do not refer to the keyspace ID as the sharding key. we will later introduce the concept of a Primary Vindex which more closely resembles the NoSQL sharding key. + +Mapping to a `keyspace ID`, and then to a shard, gives us the flexibility to reshard the data with minimal disruption because the `keyspace ID` of each row remains unchanged through the process. + +## Vindex + +The Sharding Key is a concept that was introduced by NoSQL datastores. It is based on the fact that there is only one access path to the data, which is the Key. However, relational databases are more versatile about the data and their relationships. So, sharding a database by only designating a sharding key is often insufficient. + +If one were to draw an analogy, the indexes in a database would be the equivalent of the key in a NoSQL datastore, except that databases allow you to define multiple indexes per table, and there are many types of indexes. Extending this analogy to a sharded database results in different types of cross-shard indexes. In Vitess, these are called Vindexes. + +Simplistically stated, a Vindex provides a way to map a column value to a `keyspace ID`. This mapping can be used to identify the location of a row. A variety of vindexes are available to choose from with different trade-offs, and you can choose one that best suits your needs. + +Vindexes offer many flexibilities: + +* A table can have multiple Vindexes. +* Vindexes could be NonUnique, which allows a column value to yield multiple keyspace IDs. +* They could be a simple function or be based on a lookup table. +* They could be shared across multiple tables. +* Custom Vindexes can be plugged in, and Vitess will still know how to reshard using such Vindexes. + +### The Primary Vindex + +The Primary Vindex is analogous to a database primary key. Every sharded table must have one defined. A Primary Vindex must be unique: given an input value, it must produce a single keyspace ID. This unique mapping will be used at the time of insert to decide the target shard for a row. Conceptually, this is also equivalent to the NoSQL Sharding Key, and we often refer to the Primary Vindex as the Sharding Key. + +Uniqueness for a Primary Vindex does not mean that the column has to be a primary key or unique in the MySQL schema. You can have multiple rows that map to the same keyspace ID. The Vindex uniqueness constraint is only used to make sure that all rows for a keyspace ID live in the same shard. + +However, there is a subtle difference: NoSQL datastores let you choose the Sharding Key, but the Sharding Scheme is generally hardcoded in the engine. In Vitess, the choice of Vindex lets you control how a column value maps to a keyspace ID. In other words, a Primary Vindex in Vitess not only defines the Sharding Key, it also decides the Sharding Scheme. + +Vindexes come in many varieties. Some of them can be used as Primary Vindex, and others have different purposes. The following sections will describe their properties. + +### Secondary Vindexes + +Secondary Vindexes are additional vindexes you can define against other columns of a table offering you optimizations for WHERE clauses that do not use the Primary Vindex. Secondary Vindexes return a single or a limited set of `keyspace IDs` which will allow VTGate to only target shards where the relevant data is present. In the absence of a Secondary Vindex, VTGate would have to send the query to all shards. + +Secondary Vindexes are also commonly known as cross-shard indexes. It is important to note that Secondary Vindexes are only for making routing decisions. The underlying database shards will most likely need traditional indexes on those same columns. + +### Unique and NonUnique Vindex + +A Unique Vindex is one that yields at most one keyspace ID for a given input. Knowing that a Vindex is Unique is useful because VTGate can push down some complex queries into VTTablet if it knows that the scope of that query cannot exceed a shard. Uniqueness is also a prerequisite for a Vindex to be used as Primary Vindex. + +A NonUnique Vindex is analogous to a database non-unique index. It is a secondary index for searching by an alternate WHERE clause. An input value could yield multiple keyspace IDs, and rows could be matched from multiple shards. For example, if a table has a `name` column that allows duplicates, you can define a cross-shard NonUnique Vindex for it, and this will let you efficiently search for users that match a certain `name`. + +### Functional and Lookup Vindex + +A Functional Vindex is one where the column value to keyspace ID mapping is pre-established, typically through an algorithmic function. In contrast, a Lookup Vindex is one that gives you the ability to create an association between a value and a keyspace ID, and recall it later when needed. + +Typically, the Primary Vindex is Functional. In some cases, it is the identity function where the input value yields itself as the kesypace id. However, one could also choose other algorithms like hashing or mod functions. + +A Lookup Vindex is usually backed by a lookup table. This is analogous to the traditional database index, except that it is cross-shard. At the time of insert, the computed keyspace ID of the row is stored in the lookup table against the column value. + +### Shared Vindexes + +Relational databases encourage normalization, which lets you split data into different tables to avoid duplication in the case of one-to-many relationships. In such cases, a key is shared between the two tables to indicate that the rows are related, aka `Foreign Key`. + +In a sharded environment, it is often beneficial to keep those rows in the same shard. If a Lookup Vindex was created on the foreign key column of each of those tables, you would find that the backing tables would actually be identical. In such cases, Vitess lets you share a single Lookup Vindex for multiple tables. Of these, one of them is designated as the owner, which is responsible for creating and deleting these associations. The other tables just reuse these associations. + +Caveat: If you delete a row from the owner table, Vitess will not perform cascading deletes. This is mainly for efficiency reasons; The application is likely capable of doing this more efficiently. + +Functional Vindexes can be also be shared. However, there is no concept of ownership because the column to keyspace ID mapping is pre-established. + +### Orthogonality + +The previously described properties are mostly orthogonal. Combining them gives rise to the following valid categories: + +* **Functional Unique**: This is the most popular category because it is the one best suited to be a Primary Vindex. +* **Functional NonUnique**: There are currently no use cases that need this category. +* **Lookup Unique Owned**: This gets used for optimizing high QPS queries that do not use the Primary Vindex columns in their WHERE clause. There is a price to pay: You incur an extra write to the lookup table for insert and delete operations, and an extra lookup for read operations. However, it is worth it if you do not want these high QPS queries to be sent to all shards. +* **Lookup Unique Unowned**: This category is used as an optimization as described in the Shared Vindexes section. +* **Lookup NonUnique Owned**: This gets used for high QPS queries on columns that are non-unique. +* **Lookup NonUnique Unowned**: You would rarely have to use this category because it is unlikely that you will be using a column as foreign key that is not unique within a shard. But it is theoretically possible. + +Of the above categories, `Functional Unique` and `Lookup Unique Unowned` Vindexes can be Primary. This is because those are the only ones that are unique and have the column to keyspace ID mapping pre-established. This is required because the Primary Vindex is responsible for assigning the keyspace ID for a row when it is created. + +However, it is generally not recommended to use a Lookup vindex as Primary because it is too slow for resharding. If absolutely unavoidable, you can use a Lookup Vindex as Primary. In such cases, it is recommended that you add a `keyspace ID` column to such tables. While resharding, Vitess can use that column to efficiently compute the target shard. You can even configure Vitess to auto-populate that column on inserts. This is done using the reverse map feature explained below. + +### How vindexes are used + +#### Cost + +Vindexes have costs. For routing a query, the Vindex with the lowest cost is chosen. The current costs are: + +Vindex Type | Cost +----------- | ---- +Indentity | 0 +Functional | 1 +Lookup Unique | 10 +Lookup NonUnique | 20 + +#### Select + +In the case of a simple select, Vitess scans the WHERE clause to match references to Vindex columns and chooses the best one to use. If there is no match and the query is simple without complex constructs like aggregates, etc, it is sent to all shards. + +Vitess can handle more complex queries. For now, you can refer to the [design doc](https://github.com/vitessio/vitess/blob/master/doc/V3HighLevelDesign.md) on how it handles them. + +#### Insert + +* The Primary Vindex is used to generate a keyspace ID. +* The keyspace ID is validated against the rest of the Vindexes on the table. There must exist a mapping from the column value to the keyspace ID. +* If a column value was not provided for a Vindex and the Vindex is capable of reverse mapping a keyspace ID to an input value, that function is used to auto-fill the column. If there is no reverse map, it is an error. + +#### Update + +The WHERE clause is used to route the update. Updating the value of a Vindex column is supported, but with a restriction: the change in the column value should not result in the row being moved from one shard to another. A workaround is to perform a delete followed by insert, which works as expected. + +#### Delete + +If the table owns lookup vindexes, then the rows to be deleted are first read and the associated Vindex entries are deleted. Following this, the query is routed according to the WHERE clause. + +### Predefined Vindexes + +Vitess provides the following predefined Vindexes: + +Name | Type | Description | Primary | Reversible | Cost +---- | ---- | ----------- | ------- | ---------- | ---- +binary | Functional Unique | Identity | Yes | Yes | 0 +binary\_md5 | Functional Unique | md5 hash | Yes | No | 1 +hash | Functional Unique | 3DES null-key hash | Yes | Yes | 1 +lookup | Lookup NonUnique | Lookup table non-unique values | No | Yes | 20 +lookup\_unique | Lookup Unique | Lookup table unique values | If unowned | Yes | 10 +consistent\_lookup | Lookup NonUnique | Lookup table non-unique values | No | No | 20 +consistent\_lookup\_unique | Lookup Unique | Lookup table unique values | unowned | No | 10 +numeric | Functional Unique | Identity | Yes | Yes | 0 +numeric\_static\_map | Functional Unique | A JSON file that maps input values to keyspace IDs | Yes | No | 1 +unicode\_loose\_md5 | Functional Unique | Case-insensitive (UCA level 1) md5 hash | Yes | No | 1 +reverse\_bits | Functional Unique | Bit Reversal | Yes | Yes | 1 + +[Consistent lookup vindexes](consistent-lookup) are a new category of vindexes that are meant to replace the existing lookup vindexes. For the time being, they have a different name to allow for users to switch back and forth. + +Custom vindexes can also be plugged in as needed. + +## Sequences + +Auto-increment columns do not work very well for sharded tables. [Vitess sequences](../../reference/vitess-sequences) solve this problem. Sequence tables must be specified in the VSchema, and then tied to table columns. At the time of insert, if no value is specified for such a column, VTGate will generate a number for it using the sequence table. + +## Reference tables + +Vitess allows you to create an unsharded table and deploy it into all shards of a sharded keyspace. The data in such a table is assumed to be identical for all shards. In this case, you can specify that the table is of type `reference`, and should not specify any vindex for it. Any joins of this table with an unsharded table will be treated as a local join. + +Typically, such a table has a canonical source in an unsharded keyspace, and the copies in the sharded keyspace are kept up-to-date through VReplication. + +## VSchema + +As mentioned in the beginning of the document, a VSchema is needed to tie together all the databases that Vitess manages. For a very trivial setup where there is only one unsharded keyspace, there is no need to specify a VSchema because Vitess will know that there is no other place to route a query. + +If you have multiple unsharded keyspaces, you can still avoid defining a VSchema in one of two ways: + +1. Connect to a keyspace and all queries are sent to it. +2. Connect to Vitess without specifying a keyspace, but use qualified names for tables, like `keyspace.table` in your queries. + +However, once the setup exceeds the above complexity, VSchemas become a necessity. Vitess has a [working demo](https://github.com/vitessio/vitess/tree/master/examples/demo) of VSchemas. + +### ApplyVSchema + +You can use the vtctlclient ApplyVSchema command to apply a VSchema: + +``` +ApplyVSchema {-vschema= || -vschema_file= || -sql= || -sql_file=} [-cells=c1,c2,...] [-skip_rebuild] [-dry-run] +``` + +The following sections document the various features highlighted with snippets pulled from the demo. + +### Unsharded Table + +The following snippets show the necessary configs for creating a table in an unsharded keyspace: + +Schema: + +``` sql +# lookup keyspace +create table name_user_idx(name varchar(128), user_id bigint, primary key(name, user_id)); +``` + +VSchema: + +``` json +// lookup keyspace +{ + "sharded": false, + "tables": { + "name_user_idx": {} + } +} +``` + +For a normal unsharded table, the VSchema only needs to know the table name. No additional metadata is needed. + +### Sharded Table With Simple Primary Vindex + +To create a sharded table with a simple Primary Vindex, the VSchema requires more information: + +Schema: + +``` sql +# user keyspace +create table user(user_id bigint, name varchar(128), primary key(user_id)); +``` + +VSchema: + +``` json +// user keyspace +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "user": { + "column_vindexes": [ + { + "column": "user_id", + "name": "hash" + } + ] + } + } +} +``` + +Because Vindexes can be shared, the JSON requires them to be specified in a separate `vindexes` section, and then referenced by name from the `tables` section. The VSchema above simply states that `user_id` uses `hash` as Primary Vindex. The first Vindex of every table must be the Primary Vindex. + +### Specifying A Sequence + +Since user is a sharded table, it will be beneficial to tie it to a Sequence. However, the sequence must be defined in the lookup (unsharded) keyspace. It is then referred from the user (sharded) keyspace. In this example, we are designating the user_id (Primary Vindex) column as the auto-increment. + +Schema: + +``` sql +# lookup keyspace +create table user_seq(id int, next_id bigint, cache bigint, primary key(id)) comment 'vitess_sequence'; +insert into user_seq(id, next_id, cache) values(0, 1, 3); +``` + +For the sequence table, `id` is always 0. `next_id` starts off as 1, and the cache is usually a medium-sized number like 1000. In our example, we are using a small number to showcase how it works. + +VSchema: + +``` json +// lookup keyspace +{ + "sharded": false, + "tables": { + "user_seq": { + "type": "sequence" + } + } +} + +// user keyspace +{ + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + } + }, + "tables": { + "user": { + "column_vindexes": [ + { + "column": "user_id", + "name": "hash" + } + ], + "auto_increment": { + "column": "user_id", + "sequence": "user_seq" + } + } + } +} +``` + +### Specifying A Secondary Vindex + +The following snippet shows how to configure a Secondary Vindex that is backed by a lookup table. In this case, the lookup table is configured to be in the unsharded lookup keyspace: + +Schema: + +``` sql +# lookup keyspace +create table name_user_idx(name varchar(128), user_id bigint, primary key(name, user_id)); +``` + +VSchema: + +``` json +// lookup keyspace +{ + "sharded": false, + "tables": { + "name_user_idx": {} + } +} + +// user keyspace +{ + "sharded": true, + "vindexes": { + "name_user_idx": { + "type": "lookup_hash", + "params": { + "table": "name_user_idx", + "from": "name", + "to": "user_id" + }, + "owner": "user" + } + }, + "tables": { + "user": { + "column_vindexes": [ + { + "column": "name", + "name": "name_user_idx" + } + ] + } + } +} +``` + +To recap, a checklist for creating the shared Secondary Vindex is: + +* Create physical `name_user_idx` table in lookup database. +* Define a routing for it in the lookup VSchema. +* Define a Vindex as type `lookup_hash` that points to it. Ensure that the `params` match the table name and columns. +* Define the owner for the Vindex as the `user` table. +* Specify that `name` uses the Vindex. + +Currently, these steps have to be currently performed manually. However, extended DDLs backed by improved automation will simplify these tasks in the future. + +### Advanced usage + +The examples/demo also shows more tricks you can perform: + +* The `music` table uses a secondary lookup vindex `music_user_idx`. However, this lookup vindex is itself a sharded table. +* `music_extra` shares `music_user_idx` with `music`, and uses it as Primary Vindex. +* `music_extra` defines an additional Functional Vindex called `keyspace_id` which the demo auto-populates using the reverse mapping capability. +* There is also a `name_info` table that showcases a case-insensitive Vindex `unicode_loose_md5`. + +## Roadmap + +VSchema is still evolving. Features are mostly added on demand. The following features are currently on our roadmap: + +* DDL support +* Lookup Vindex backfill +* Pinned tables: This feature will allow unsharded tables to be pinned to a keyspace id. This avoids the need for a separate unsharded keyspace to contain them. diff --git a/content/zh/docs/19.0/user-guides/_index.md b/content/zh/docs/19.0/user-guides/_index.md new file mode 100644 index 000000000..e37eddc60 --- /dev/null +++ b/content/zh/docs/19.0/user-guides/_index.md @@ -0,0 +1,92 @@ +--- +title: User Guides +description: Practical Guides for Most Scenarios +weight: 3 +--- +{{< info >}} +因为这些文档不维护，所以它们是旧的。 +{{< /info >}} + +## Platform support + +We continuously test against Ubuntu 14.04 (Trusty) and Debian 8 (Jessie). +Other Linux distributions should work as well. + +## Database support + +Vitess supports [MySQL 5.6](http://dev.mysql.com/doc/refman/5.6/en/), +[MariaDB 10.0](https://downloads.mariadb.org/mariadb/10.0.21/), and any +newer versions like MySQL 5.7, etc. Vitess also supports Percona's +variations of these versions. + +### Relational capabilities + +Vitess attempts to leverage the capabilities of the underlying MySQL +instances to the fullest extent. In this respect, any query that can +be passed through to a single keyspace, shard or set of shards will +be sent to the MySQL servers as is. + +This approach allows you to exploit the full capabilities of MySQL +as long as the relationships and constraints are within one shard (or +unsharded keyspace). + +For relationships that go beyond shards, Vitess provides +support through the [VSchema](../schema-management/vschema). + +### Schema management + +Vitess supports several functions for looking at your schema and +validating its consistency across tablets in a shard or across all +shards in a keyspace. + +In addition, Vitess supports +[data definition statements](https://dev.mysql.com/doc/refman/5.6/en/sql-data-definition-statements.html) +that create, modify, or delete database tables. Vitess executes +schema changes on the master tablet within each shard, and those +changes then propagate to slave tablets via replication. Vitess does +not support other types of DDL statements, such as those that affect +stored procedures or grants. + +Before executing a schema change, Vitess validates the SQL syntax +and determines the impact of the change. It also does a pre-flight +check to ensure that the update can be applied to your schema. In +addition, to avoid reducing the availability of your entire system, +Vitess rejects changes that exceed a certain scope. + +See the [Schema Management](../schema-management) +section of this guide for more information. + +## Supported clients + +The VTGate server is the main entry point that applications use +to connect to Vitess. + +VTGate understands the MySQL binary protocol. So, any client that +can directly talk to MySQL can also use Vitess. + +Additionally, VTGate exposes its functionality through a +[gRPC](http://www.grpc.io/) API which has support for multiple languages. + +Accessing Vitess through gRPC has some minor advantages over the MySQL +protocol: + +* You can send requests with bind variables, which is slightly more + efficient and secure than building the full text query. +* You can exploit the statelessness of connections. For example, you + can start a transaction using one VTGate server, and complete it + using another. + +Vitess currently provides gRPC based connectors for Java (JDBC) and Go +(database/sql). All others can use the native MySQL drivers instead. The +native MySQL drivers for Java and Go should also work. + +## Backups + +Vitess supports data backups to either a network mount (e.g. NFS) or to a blob store. +Backup storage is implemented through a pluggable interface, +and we currently have plugins available for Google Cloud Storage, Amazon S3, +and Ceph. + +See the [Backing Up and Restoring Data](backup-and-restore) section +of this guide for more information about creating and restoring data +backups with Vitess. diff --git a/content/zh/docs/19.0/user-guides/backup-and-restore.md b/content/zh/docs/19.0/user-guides/backup-and-restore.md new file mode 100644 index 000000000..27b30dead --- /dev/null +++ b/content/zh/docs/19.0/user-guides/backup-and-restore.md @@ -0,0 +1,253 @@ +--- +title: Backing Up and Restoring Data +weight: 4 +--- + +This document explains how to create and restore data backups with +Vitess. Vitess uses backups for two purposes: + +* Provide a point-in-time backup of the data on a tablet. +* Bootstrap new tablets in an existing shard. + +## Prerequisites + +Vitess stores data backups on a Backup Storage service, which is a +[pluggable interface](https://github.com/vitessio/vitess/blob/master/go/vt/mysqlctl/backupstorage/interface.go). + +Currently, we have plugins for: + +* A network-mounted path (e.g. NFS) +* Google Cloud Storage +* Amazon S3 +* Ceph + +Before you can back up or restore a tablet, you need to ensure that the +tablet is aware of the Backup Storage system that you are using. To do so, +use the following command-line flags when starting a vttablet that has +access to the location where you are storing backups. + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Flags
    backup_storage_implementationSpecifies the implementation of the Backup Storage interface to + use.

    + Current plugin options available are: +
      +
    • file: NFS or any other filesystem-mounted network + drive.
      • +
    • gcs: Google Cloud Storage.
      • +
    • s3: Amazon S3.
      • +
    • ceph: Ceph Object Gateway S3 API.
      • +
    +
    backup_storage_hookIf set, the contents of every file to backup is sent to a hook. The + hook receives the data for each file on stdin. It should echo the + transformed data to stdout. Anything the hook prints to stderr will + be printed in the vttablet logs.
    + Hooks should be located in the vthook subdirectory of the + VTROOT directory.
    + The hook receives a -operation write or a + -operation read parameter depending on the direction + of the data processing. For instance, write would be for + encryption, and read would be for decryption.
    +
    backup_storage_compressThis flag controls if the backups are compressed by the Vitess code. + By default it is set to true. Use + -backup_storage_compress=false to disable.
    + This is meant to be used with a -backup_storage_hook + hook that already compresses the data, to avoid compressing the data + twice. +
    file_backup_storage_rootFor the file plugin, this identifies the root directory + for backups. +
    gcs_backup_storage_bucketFor the gcs plugin, this identifies the + bucket + to use.
    s3_backup_aws_regionFor the s3 plugin, this identifies the AWS region.
    s3_backup_storage_bucketFor the s3 plugin, this identifies the AWS S3 + bucket.
    ceph_backup_storage_configFor the ceph plugin, this identifies the path to a text + file with a JSON object as configuration. The JSON object requires the + following keys: accessKey, secretKey, + endPoint and useSSL. Bucket name is computed + from keyspace name and shard name is separated for different + keyspaces / shards.
    restore_from_backupIndicates that, when started with an empty MySQL instance, the + tablet should restore the most recent backup from the specified + storage plugin.
    + +### Authentication + +Note that for the Google Cloud Storage plugin, we currently only +support +[Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). +It means that access to Cloud Storage is automatically granted by virtue of +the fact that you're already running within Google Compute Engine or Container +Engine. + +For this to work, the GCE instances must have been created with +the [scope](https://cloud.google.com/compute/docs/authentication#using) that +grants read-write access to Cloud Storage. When using Container Engine, you can +do this for all the instances it creates by adding `--scopes storage-rw` to the +`gcloud container clusters create` command as shown in the [Vitess on Kubernetes +guide](../../tutorials/kubernetes#start-a-container-engine-cluster). + +## Creating a backup + +Run the following vtctl command to create a backup: + +``` sh +vtctl Backup +``` + +In response to this command, the designated tablet performs the following +sequence of actions: + +1. Switches its type to `BACKUP`. After this step, the tablet is no + longer used by vtgate to serve any query. + +1. Stops replication, get the current replication position (to be saved in the + backup along with the data). + +1. Shuts down its mysqld process. + +1. Copies the necessary files to the Backup Storage implementation that was + specified when the tablet was started. Note if this fails, we still keep + going, so the tablet is not left in an unstable state because of a storage + failure. + +1. Restarts mysqld. + +1. Restarts replication (with the right semi-sync flags corresponding to its + original type, if applicable). + +1. Switches its type back to its original type. After this, it will most likely + be behind on replication, and not used by vtgate for serving until it catches + up. + +## Restoring a backup + +When a tablet starts, Vitess checks the value of the +`-restore_from_backup` command-line flag to determine whether +to restore a backup to that tablet. + +* If the flag is present, Vitess tries to restore the most recent backup from + the Backup Storage system when starting the tablet. +* If the flag is absent, Vitess does not try to restore a backup to the + tablet. This is the equivalent of starting a new tablet in a new shard. + +As noted in the [Prerequisites](#prerequisites) section, the flag is +generally enabled all of the time for all of the tablets in a shard. +By default, if Vitess cannot find a backup in the Backup Storage system, +the tablet will start up empty. This behavior allows you to bootstrap a new +shard before any backups exist. + +If the `-wait_for_backup_interval` flag is set to a value greater than zero, +the tablet will instead keep checking for a backup to appear at that interval. +This can be used to ensure tablets launched concurrently while an initial backup +is being seeded for the shard (e.g. uploaded from cold storage or created by +another tablet) will wait until the proper time and then pull the new backup +when it's ready. + +``` sh +vttablet ... -backup_storage_implementation=file \ + -file_backup_storage_root=/nfs/XXX \ + -restore_from_backup +``` + +## Managing backups + +**vtctl** provides two commands for managing backups: + +* [ListBackups](../../reference/vtctl#listbackups) displays the + existing backups for a keyspace/shard in chronological order. + + ``` sh + vtctl ListBackups + ``` + +* [RemoveBackup](../../reference/vtctl#removebackup) deletes a + specified backup for a keyspace/shard. + + ``` sh + RemoveBackup + ``` + +## Bootstrapping a new tablet + +Bootstrapping a new tablet is almost identical to restoring an existing tablet. +The only thing you need to be cautious about is that the tablet specifies its +keyspace, shard and tablet type when it registers itself at the topology. +Specifically, make sure that the following vttablet parameters are set: + +``` sh + -init_keyspace + -init_shard + -init_tablet_type replica|rdonly +``` + +The bootstrapped tablet will restore the data from the backup and then apply +changes, which occurred after the backup, by restarting replication. + + +## Backup Frequency + +We recommend to take backups regularly e.g. you should set up a cron +job for it. + +To determine the proper frequency for creating backups, consider +the amount of time that you keep replication logs and allow enough +time to investigate and fix problems in the event that a backup +operation fails. + +For example, suppose you typically keep four days of replication logs +and you create daily backups. In that case, even if a backup fails, +you have at least a couple of days from the time of the failure to +investigate and fix the problem. + +## Concurrency + +The back-up and restore processes simultaneously copy and either +compress or decompress multiple files to increase throughput. You +can control the concurrency using command-line flags: + +* The vtctl [Backup](../../reference/vtctl#backup) command uses the + `-concurrency` flag. +* vttablet uses the `-restore_concurrency` flag. + +If the network link is fast enough, the concurrency matches the CPU +usage of the process during the backup or restore process. diff --git a/content/zh/docs/19.0/user-guides/img/vitesstransportsecuritymodel.svg b/content/zh/docs/19.0/user-guides/img/vitesstransportsecuritymodel.svg new file mode 100644 index 000000000..db116cdeb --- /dev/null +++ b/content/zh/docs/19.0/user-guides/img/vitesstransportsecuritymodel.svg @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/content/zh/docs/19.0/user-guides/reparenting.md b/content/zh/docs/19.0/user-guides/reparenting.md new file mode 100644 index 000000000..1c0069d0a --- /dev/null +++ b/content/zh/docs/19.0/user-guides/reparenting.md @@ -0,0 +1,93 @@ +--- +title: Reparenting +weight: 5 +--- + +**Reparenting** is the process of changing a shard's master tablet from one host to another or changing a slave tablet to have a different master. Reparenting can be initiated manually or it can occur automatically in response to particular database conditions. As examples, you might reparent a shard or tablet during a maintenance exercise or automatically trigger reparenting when a master tablet dies. + +This document explains the types of reparenting that Vitess supports: + +* [Active reparenting](https://vitess.io/user-guide/reparenting/#active-reparenting) occurs when the Vitess toolchain manages the entire reparenting process. +* [External reparenting](https://vitess.io/user-guide/reparenting/#external-reparenting) occurs when another tool handles the reparenting process, and the Vitess toolchain just updates its topology server, replication graph, and serving graph to accurately reflect master-slave relationships. + +**Note:** The `InitShardMaster` command defines the initial parenting relationships within a shard. That command makes the specified tablet the master and makes the other tablets in the shard slaves that replicate from that master. + +## MySQL requirements + +### GTIDs + +Vitess requires the use of global transaction identifiers ([GTIDs](https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-concepts.html)) for its operations: + +* During active reparenting, Vitess uses GTIDs to initialize the replication process and then depends on the GTID stream to be correct when reparenting. (During external reparenting, Vitess assumes the external tool manages the replication process.) +* During resharding, Vitess uses GTIDs for [filtered replication](https://vitess.io/user-guide/sharding/#filtered-replication), the process by which source tablet data is transferred to the proper destination tablets. + +### Semisynchronous replication + +Vitess does not depend on [semisynchronous replication](https://dev.mysql.com/doc/refman/5.6/en/replication-semisync.html) but does work if it is implemented. Larger Vitess deployments typically do implement semisynchronous replication. + +### [Active Reparenting](#active-reparenting) + +You can use the following `vtctl` commands to perform reparenting operations: + +* `PlannedReparentShard` +* `EmergencyReparentShard` + +Both commands lock the Shard record in the global topology server. The two commands cannot run in parallel, nor can either command run in parallel with the `InitShardMaster` command. + +The two commands are both dependent on the global topology server being available, and they both insert rows in the topology server's `_vt.reparent_journal` table. As such, you can review your database's reparenting history by inspecting that table. + +### PlannedReparentShard: Planned reparenting + +The `PlannedReparentShard` command reparents a healthy master tablet to a new master. The current and new master must both be up and running. + +This command performs the following actions: + +1. Puts the current master tablet in read-only mode. +2. Shuts down the current master's query service, which is the part of the system that handles user SQL queries. At this point, Vitess does not handle any user SQL queries until the new master is configured and can be used a few seconds later. +3. Retrieves the current master's replication position. +4. Instructs the master-elect tablet to wait for replication data and then begin functioning as the new master after that data is fully transferred. +5. Ensures replication is functioning properly via the following steps: + - On the master-elect tablet, insert an entry in a test table and then update the global Shard object's MasterAlias record. + - In parallel on each slave, including the old master, set the new master and wait for the test entry to replicate to the slave tablet. (Slave tablets that had not been replicating before the command was called are left in their current state and do not start replication after the reparenting process.) + - Start replication on the old master tablet so it catches up to the new master. + +In this scenario, the old master's tablet type transitions to `spare`. If health checking is enabled on the old master, it will likely rejoin the cluster as a replica on the next health check. To enable health checking, set the `target_tablet_type` parameter when starting a tablet. That parameter indicates what type of tablet that tablet tries to be when healthy. When it is not healthy, the tablet type changes to spare. + +### EmergencyReparentShard: Emergency reparenting + +The `EmergencyReparentShard` command is used to force a reparent to a new master when the current master is unavailable. The command assumes that data cannot be retrieved from the current master because it is dead or not working properly. + +As such, this command does not rely on the current master at all to replicate data to the new master. Instead, it makes sure that the master-elect is the most advanced in replication within all of the available slaves. + +**Important**: Before calling this command, you must first identify the slave with the most advanced replication position as that slave must be designated as the new master. You can use the `[vtctl ShardReplicationPositions](https://vitess.io/reference/vtctl/#shardreplicationpositions)` command to determine the current replication positions of a shard's slaves. + +This command performs the following actions: + +1. Determines the current replication position on all of the slave tablets and confirms that the master-elect tablet has the most advanced replication position. +2. Promotes the master-elect tablet to be the new master. In addition to changing its tablet type to master, the master-elect performs any other changes that might be required for its new state. +3. Ensures replication is functioning properly via the following steps: + - On the master-elect tablet, Vitess inserts an entry in a test table and then updates the `MasterAlias` record of the global Shard object. + - In parallel on each slave, excluding the old master, Vitess sets the master and waits for the test entry to replicate to the slave tablet. (Slave tablets that had not been replicating before the command was called are left in their current state and do not start replication after the reparenting process.) + +## [External Reparenting](#external-reparenting) + +External reparenting occurs when another tool handles the process of changing a shard's master tablet. After that occurs, the tool needs to call the `[vtctl TabletExternallyReparented](https://vitess.io/reference/vtctl/#tabletexternallyreparented)` command to ensure that the topology server, replication graph, and serving graph are updated accordingly. + +That command performs the following operations: + +1. Locks the shard in the global topology server. +2. Reads the `Shard` object from the global topology server. +3. Reads all of the tablets in the replication graph for the shard. Vitess does allow partial reads in this step, which means that Vitess will proceed even if a data center is down as long as the data center containing the new master is available. +4. Ensures that the new master's state is updated correctly and that the new master is not a MySQL slave of another server. It runs the MySQL `show slave status` command, ultimately aiming to confirm that the MySQL `reset slave` command already executed on the tablet. +5. Updates, for each slave, the topology server record and replication graph to reflect the new master. If the old master does not return successfully in this step, Vitess changes its tablet type to spare to ensure that it does not interfere with ongoing operations. +6. Updates the `Shard` object to specify the new master. + +The `TabletExternallyReparented` command fails in the following cases: + +* The global topology server is not available for locking and modification. In that case, the operation fails completely. + +Active reparenting might be a dangerous practice in any system that depends on external reparents. You can disable active reparents by starting `vtctld` with the `--disable_active_reparents` flag set to true. (You cannot set the flag after `vtctld` is started.) + +## Fixing Replication + +A tablet can be orphaned after a reparenting if it is unavailable when the reparent operation is running but then recovers later on. In that case, you can manually reset the tablet's master to the current shard master using the `vtctl ReparentTablet` command. You can then restart replication on the tablet if it was stopped by calling the `vtctl StartSlave` command. diff --git a/content/zh/docs/19.0/user-guides/topology-service.md b/content/zh/docs/19.0/user-guides/topology-service.md new file mode 100644 index 000000000..b7cf87059 --- /dev/null +++ b/content/zh/docs/19.0/user-guides/topology-service.md @@ -0,0 +1,587 @@ +--- +title: Topology Service +weight: 6 +--- + +This document describes the Topology Service, a key part of the Vitess +architecture. This service is exposed to all Vitess processes, and is used to +store small pieces of configuration data about the Vitess cluster, and provide +cluster-wide locks. It also supports watches, and master election. + +Concretely, the Topology Service features are implemented by +a [Lock Server](http://en.wikipedia.org/wiki/Distributed_lock_manager), referred +to as Topology Server in the rest of this document. We use a plug-in +implementation and we support multiple Lock Servers (Zookeeper, etcd, Consul, …) +as backends for the service. + +## Requirements and usage + +The Topology Service is used to store information about the Keyspaces, the +Shards, the Tablets, the Replication Graph, and the Serving Graph. We store +small data structures (a few hundred bytes) per object. + +The main contract for the Topology Server is to be very highly available and +consistent. It is understood it will come at a higher latency cost and very low +throughput. + +We never use the Topology Server as an RPC mechanism, nor as a storage system +for logs. We never depend on the Topology Server being responsive and fast to +serve every query. + +The Topology Server must also support a Watch interface, to signal when certain +conditions occur on a node. This is used for instance to know when keyspaces +topology changes (for resharding for instance). + +### Global vs local + +We differentiate two instances of the Topology Server: the Global instance, and +the per-cell Local instance: + +* The Global instance is used to store global data about the topology that + doesn’t change very often, for instance information about Keyspaces and + Shards. The data is independent of individual instances and cells, and needs + to survive a cell going down entirely. +* There is one Local instance per cell, that contains cell-specific information, + and also rolled-up data from the global + local cell to make it easier for + clients to find the data. The Vitess local processes should not use the Global + topology instance, but instead the rolled-up data in the Local topology + server as much as possible. + +The Global instance can go down for a while and not impact the local cells (an +exception to that is if a reparent needs to be processed, it might not work). If +a Local instance goes down, it only affects the local tablets in that instance +(and then the cell is usually in bad shape, and should not be used). + +Furthermore, the Vitess processes will not use the Global nor the Local Topology +Server to serve individual queries. They only use the Topology Server to get the +topology information at startup and in the background, but never to directly +serve queries. + +### Recovery + +If a local Topology Server dies and is not recoverable, it can be wiped out. All +the tablets in that cell then need to be restarted so they re-initialize their +topology records (but they won’t lose any MySQL data). + +If the global Topology Server dies and is not recoverable, this is more of a +problem. All the Keyspace / Shard objects have to be re-created. Then the cells +should recover. + +## Global data + +This section describes the data structures stored in the global instance of the +topology server. + +### Keyspace + +The Keyspace object contains various information, mostly about sharding: how is +this Keyspace sharded, what is the name of the sharding key column, is this +Keyspace serving data yet, how to split incoming queries, … + +An entire Keyspace can be locked. We use this during resharding for instance, +when we change which Shard is serving what inside a Keyspace. That way we +guarantee only one operation changes the keyspace data concurrently. + +### Shard + +A Shard contains a subset of the data for a Keyspace. The Shard record in the +global topology contains: + +* the Master tablet alias for this shard (that has the MySQL master). +* the sharding key range covered by this Shard inside the Keyspace. +* the tablet types this Shard is serving (master, replica, batch, …), per cell + if necessary. +* if during filtered replication, the source shards this shard is replicating + from. +* the list of cells that have tablets in this shard. +* shard-global tablet controls, like blacklisted tables no tablet should serve + in this shard. + +A Shard can be locked. We use this during operations that affect either the +Shard record, or multiple tablets within a Shard (like reparenting), so multiple +jobs don’t concurrently alter the data. + +### VSchema data + +The VSchema data contains sharding and routing information for +the [VTGate V3](https://github.com/vitessio/vitess/blob/master/doc/VTGateV3Features.md) API. + +## Local data + +This section describes the data structures stored in the local instance (per +cell) of the topology server. + +### Tablets + +The Tablet record has a lot of information about a single vttablet process +running inside a tablet (along with the MySQL process): + +* the Tablet Alias (cell+unique id) that uniquely identifies the Tablet. +* the Hostname, IP address and port map of the Tablet. +* the current Tablet type (master, replica, batch, spare, …). +* which Keyspace / Shard the tablet is part of. +* the sharding Key Range served by this Tablet. +* user-specified tag map (to store per installation data for instance). + +A Tablet record is created before a tablet can be running (either by `vtctl +InitTablet` or by passing the `init_*` parameters to the vttablet process). +The only way a Tablet record will be updated is one of: + +* The vttablet process itself owns the record while it is running, and can + change it. +* At init time, before the tablet starts. +* After shutdown, when the tablet gets deleted. +* If a tablet becomes unresponsive, it may be forced to spare to make it + unhealthy when it restarts. + +### Replication graph + +The Replication Graph allows us to find Tablets in a given Cell / Keyspace / +Shard. It used to contain information about which Tablet is replicating from +which other Tablet, but that was too complicated to maintain. Now it is just a +list of Tablets. + +### Serving graph + +The Serving Graph is what the clients use to find the per-cell topology of a +Keyspace. It is a roll-up of global data (Keyspace + Shard). vtgates only open a +small number of these objects and get all they need quickly. + +#### SrvKeyspace + +It is the local representation of a Keyspace. It contains information on what +shard to use for getting to the data (but not information about each individual +shard): + +* the partitions map is keyed by the tablet type (master, replica, batch, …) and + the values are list of shards to use for serving. +* it also contains the global Keyspace fields, copied for fast access. + +It can be rebuilt by running `vtctl RebuildKeyspaceGraph`. It is +automatically rebuilt when a tablet starts up in a cell and the SrvKeyspace +for that cell / keyspace doesn't exist yet. It will also be changed +during horizontal and vertical splits. + +#### SrvVSchema + +It is the local roll-up for the VSchema. It contains the VSchema for all +keyspaces in a single object. + +It can be rebuilt by running `vtctl RebuildVSchemaGraph`. It is automatically +rebuilt when using `vtctl ApplyVSchema` (unless prevented by flags). + +## Workflows involving the Topology Server + +The Topology Server is involved in many Vitess workflows. + +When a Tablet is initialized, we create the Tablet record, and add the Tablet to +the Replication Graph. If it is the master for a Shard, we update the global +Shard record as well. + +Administration tools need to find the tablets for a given Keyspace / Shard: +first we get the list of Cells that have Tablets for the Shard (global topology +Shard record has these) then we use the Replication Graph for that Cell / +Keyspace / Shard to find all the tablets then we can read each tablet record. + +When a Shard is reparented, we need to update the global Shard record with the +new master alias. + +Finding a tablet to serve the data is done in two stages: vtgate maintains a +health check connection to all possible tablets, and they report which keyspace +/ shard / tablet type they serve. vtgate also reads the SrvKeyspace object, to +find out the shard map. With these two pieces of information, vtgate can route +the query to the right vttablet. + +During resharding events, we also change the topology a lot. An horizontal split +will change the global Shard records, and the local SrvKeyspace records. A +vertical split will change the global Keyspace records, and the local +SrvKeyspace records. + +## Exploring the data in a Topology Server + +We store the proto3 binary data for each object. + +We use the following paths for the data, in all implementations: + +*Global Cell*: + +* CellInfo path: `cells//CellInfo` +* Keyspace: `keyspaces//Keyspace` +* Shard: `keyspaces//shards//Shard` +* VSchema: `keyspaces//VSchema` + +*Local Cell*: + +* Tablet: `tablets/-/Tablet` +* Replication Graph: `keyspaces//shards//ShardReplication` +* SrvKeyspace: `keyspaces//SrvKeyspace` +* SrvVSchema: `SvrVSchema` + +The `vtctl TopoCat` utility can decode these files when using the +`-decode_proto` option: + +``` sh +TOPOLOGY="-topo_implementation zk2 -topo_global_server_address global_server1,global_server2 -topo_global_root /vitess/global" + +$ vtctl $TOPOLOGY TopoCat -decode_proto -long /keyspaces/*/Keyspace +path=/keyspaces/ks1/Keyspace version=53 +sharding_column_name: "col1" +path=/keyspaces/ks2/Keyspace version=55 +sharding_column_name: "col2" +``` + +The `vtctld` web tool also contains a topology browser (use the `Topology` +tab on the left side). It will display the various proto files, decoded. + +## Implementations + +The Topology Server interfaces are defined in our code in `go/vt/topo/`, +specific implementations are in `go/vt/topo/`, and we also have +a set of unit tests for it in `go/vt/topo/test`. + +This part describes the implementations we have, and their specific +behavior. + +If starting from scratch, please use the `zk2`, `etcd2` or `consul` +implementations. We deprecated the old `zookeeper` and `etcd` +implementations. See the migration section below if you want to migrate. + +### Zookeeper `zk2` implementation + +This is the current implementation when using Zookeeper. (The old `zookeeper` +implementation is deprecated). + +The global cell typically has around 5 servers, distributed one in each +cell. The local cells typically have 3 or 5 servers, in different server racks / +sub-networks for higher resilience. For our integration tests, we use a single +ZK server that serves both global and local cells. + +We provide the `zk` utility for easy access to the topology data in +Zookeeper. It can list, read and write files inside any Zoopeeker server. Just +specify the `-server` parameter to point to the Zookeeper servers. Note the +vtctld UI can also be used to see the contents of the topology data. + +To configure a Zookeeper installation, let's start with the global cell +service. It is described by the addresses of the servers (comma separated list), +and by the root directory to put the Vitess data in. For instance, assuming we +want to use servers `global_server1,global_server2` in path `/vitess/global`: + +``` sh +# The root directory in the global server will be created +# automatically, same as when running this command: +# zk -server global_server1,global_server2 touch -p /vitess/global + +# Set the following flags to let Vitess use this global server: +# -topo_implementation zk2 +# -topo_global_server_address global_server1,global_server2 +# -topo_global_root /vitess/global +``` + +Then to add a cell whose local topology servers `cell1_server1,cell1_server2` +will store their data under the directory `/vitess/cell1`: + +``` sh +TOPOLOGY="-topo_implementation zk2 -topo_global_server_address global_server1,global_server2 -topo_global_root /vitess/global" + +# Reference cell1 in the global topology service: +vtctl $TOPOLOGY AddCellInfo \ + -server_address cell1_server1,cell1_server2 \ + -root /vitess/cell1 \ + cell1 +``` + +If only one cell is used, the same Zookeeper instance can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address, and very importantly a *different* root directory. + +[Zookeeper +Observers](https://zookeeper.apache.org/doc/current/zookeeperObservers.html) can +also be used to limit the load on the global Zookeeper. They are configured by +specifying the addresses of the observers in the server address, after a `|`, +for instance: +`global_server1:p1,global_server2:p2|observer1:po1,observer2:po2`. + +#### Implementation details + +We use the following paths for Zookeeper specific data, in addition to the +regular files: + +* Locks sub-directory: `locks/` (for instance: + `keyspaces//Keyspace/locks/` for a keyspace) +* Master election path: `elections/` + +Both locks and master election are implemented using ephemeral, sequential files +which are stored in their respective directory. + +### etcd `etcd2` implementation (new version of `etcd`) + +This topology service plugin is meant to use etcd clusters as storage backend +for the topology data. This topology service supports version 3 and up of the +etcd server. + +This implementation is named `etcd2` because it supersedes our previous +implementation `etcd`. Note that the storage format has been changed with the +`etcd2` implementation, i.e. existing data created by the previous `etcd` +implementation must be migrated manually (See migration section below). + +To configure an `etcd2` installation, let's start with the global cell +service. It is described by the addresses of the servers (comma separated list), +and by the root directory to put the Vitess data in. For instance, assuming we +want to use servers `http://global_server1,http://global_server2` in path +`/vitess/global`: + +``` sh +# Set the following flags to let Vitess use this global server, +# and simplify the example below: +# -topo_implementation etcd2 +# -topo_global_server_address http://global_server1,http://global_server2 +# -topo_global_root /vitess/global +TOPOLOGY="-topo_implementation etcd2 -topo_global_server_address http://global_server1,http://global_server2 -topo_global_root /vitess/global +``` + +Then to add a cell whose local topology servers +`http://cell1_server1,http://cell1_server2` will store their data under the +directory `/vitess/cell1`: + +``` sh +# Reference cell1 in the global topology service: +# (the TOPOLOGY variable is defined in the previous section) +vtctl $TOPOLOGY AddCellInfo \ + -server_address http://cell1_server1,http://cell1_server2 \ + -root /vitess/cell1 \ + cell1 +``` + +If only one cell is used, the same etcd instances can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address and, very importantly, a *different* root directory. + +#### Implementation details + +For locks, we use a subdirectory named `locks` in the directory to lock, and an +ephemeral file in that subdirectory (it is associated with a lease, whose TTL +can be set with the `-topo_etcd_lease_duration` flag, defaults to 30 +seconds). The ephemeral file with the lowest ModRevision has the lock, the +others wait for files with older ModRevisions to disappear. + +Master elections also use a subdirectory, named after the election Name, and use +a similar method as the locks, with ephemeral files. + +We store the proto3 binary data for each object (as the v3 API allows us to store binary data). + +### Consul `consul` implementation + +This topology service plugin is meant to use Consul clusters as storage backend +for the topology data. + +To configure a `consul` installation, let's start with the global cell +service. It is described by the address of a server, +and by the root node path to put the Vitess data in (it cannot start with `/`). For instance, assuming we +want to use servers `global_server:global_port` with node path +`vitess/global`: + +``` sh +# Set the following flags to let Vitess use this global server, +# and simplify the example below: +# -topo_implementation consul +# -topo_global_server_address global_server:global_port +# -topo_global_root vitess/global +TOPOLOGY="-topo_implementation consul -topo_global_server_address global_server:global_port -topo_global_root vitess/global +``` + +Then to add a cell whose local topology server +`cell1_server1:cell1_port` will store their data under the +directory `vitess/cell1`: + +``` sh +# Reference cell1 in the global topology service: +# (the TOPOLOGY variable is defined in the previous section) +vtctl $TOPOLOGY AddCellInfo \ + -server_address cell1_server1:cell1_port \ + -root vitess/cell1 \ + cell1 +``` + +If only one cell is used, the same consul instances can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address and, very importantly, a *different* root node path. + +#### Implementation details + +For locks, we use a file named `Lock` in the directory to lock, and the regular +Consul Lock API. + +Master elections use a single lock file (the Election path) and the regular +Consul Lock API. The contents of the lock file is the ID of the current master. + +Watches use the Consul long polling Get call. They cannot be interrupted, so we +use a long poll whose duration is set by the +`-topo_consul_watch_poll_duration` flag. Canceling a watch may have to +wait until the end of a polling cycle with that duration before returning. + +## Running in only one cell + +The topology service is meant to be distributed across multiple cells, and +survive single cell outages. However, one common usage is to run a Vitess +cluster in only one cell / region. This part explains how to do this, and later +on upgrade to multiple cells / regions. + +If running in a single cell, the same topology service can be used for both +global and local data. A local cell record still needs to be created, just use +the same server address and, very importantly, a *different* root node path. + +In that case, just running 3 servers for topology service quorum is probably +sufficient. For instance, 3 etcd servers. And use their address for the local +cell as well. Let's use a short cell name, like `local`, as the local data in +that topology server will later on be moved to a different topology service, +which will have the real cell name. + +### Extending to more cells + +To then run in multiple cells, the current topology service needs to be split +into a global instance and one local instance per cell. Whereas, the initial +setup had 3 topology servers (used for global and local data), we recommend to +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 `vtctl 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 +the `-cells_to_watch` command line parameter. It can then use all tablets in +all cells to route traffic. Note this is necessary to access the master in +another cell. + +After the extension to two cells, the original topo service contains both the +global topology data, and the first cell topology data. The more symmetrical +configuration we're after would be to split that original service into two: a +global one that only contains the global data (spread across both cells), and a +local one to the original cells. To achieve that split: + +* Start up a new local topology service in that original cell (3 more local + servers in that cell). +* Pick a name for that cell, different from `local`. +* Use `vtctl AddCellInfo` to configure it. +* Make sure all vtgates can see that new local cell (again, using + `-cells_to_watch`). +* Restart all vttablets to be in that new cell, instead of the `local` cell name + used before. +* Use `vtctl RemoveKeyspaceCell` to remove all mentions of the `local` cell in + all keyspaces. +* Use `vtctl RemoveCellInfo` to remove the global configurations for that + `local` cell. +* Remove all remaining data in the global topology service that are in the old + local server root. + +After this split, the configuration is completely symmetrical: + +* a global topology service, with servers in all cells. Only contains global + topology data about Keyspaces, Shards and VSchema. Typically it has 5 servers + across all cells. +* a local topology service to each cell, with servers only in that cell. Only + contains local topology data about Tablets, and roll-ups of global data for + efficient access. Typically, it has 3 servers in each cell. + +## Migration between implementations + +We provide the `topo2topo` binary file to migrate between one implementation +and another of the topology service. + +The process to follow in that case is: + +* Start from a stable topology, where no resharding or reparenting is on-going. +* Configure the new topology service so it has at least all the cells of the + source topology service. Make sure it is running. +* Run the `topo2topo` program with the right flags. `-from_implementation`, + `-from_root`, `-from_server` describe the source (old) topology + service. `-to_implementation`, `-to_root`, `-to_server` describe the + destination (new) topology service. +* Run `vtctl RebuildKeyspaceGraph` for each keyspace using the new topology + service flags. +* Run `vtctl RebuildVSchemaGraph` using the new topology service flags. +* Restart all `vtgate` using the new topology service flags. They will see the + same keyspaces / shards / tablets / vschema as before, as the topology was + copied over. +* Restart all `vttablet` using the new topology service flags. They may use the + same ports or not, but they will update the new topology when they start up, + and be visible from vtgate. +* Restart all `vtctld` processes using the new topology service flags. So that + the UI also shows the new data. + +Sample commands to migrate from deprecated `zookeeper` to `zk2` +topology would be: + +``` sh +# Let's assume the zookeeper client config file is already +# exported in $ZK_CLIENT_CONFIG, and it contains a global record +# pointing to: global_server1,global_server2 +# an a local cell cell1 pointing to cell1_server1,cell1_server2 +# +# The existing directories created by Vitess are: +# /zk/global/vt/... +# /zk/cell1/vt/... +# +# The new zk2 implementation can use any root, so we will use: +# /vitess/global in the global topology service, and: +# /vitess/cell1 in the local topology service. + +# Create the new topology service roots in global and local cell. +zk -server global_server1,global_server2 touch -p /vitess/global +zk -server cell1_server1,cell1_server2 touch -p /vitess/cell1 + +# Store the flags in a shell variable to simplify the example below. +TOPOLOGY="-topo_implementation zk2 -topo_global_server_address global_server1,global_server2 -topo_global_root /vitess/global" + +# Reference cell1 in the global topology service: +vtctl $TOPOLOGY AddCellInfo \ + -server_address cell1_server1,cell1_server2 \ + -root /vitess/cell1 \ + cell1 + +# Now copy the topology. Note the old zookeeper implementation doesn't need +# any server or root parameter, as it reads ZK_CLIENT_CONFIG. +topo2topo \ + -from_implementation zookeeper \ + -to_implementation zk2 \ + -to_server global_server1,global_server2 \ + -to_root /vitess/global \ + +# Rebuild SvrKeyspace objects in new service, for each keyspace. +vtctl $TOPOLOGY RebuildKeyspaceGraph keyspace1 +vtctl $TOPOLOGY RebuildKeyspaceGraph keyspace2 + +# Rebuild SrvVSchema objects in new service. +vtctl $TOPOLOGY RebuildVSchemaGraph + +# Now restart all vtgate, vttablet, vtctld processes replacing: +# -topo_implementation zookeeper +# With: +# -topo_implementation zk2 +# -topo_global_server_address global_server1,global_server2 +# -topo_global_root /vitess/global +# +# After this, the ZK_CLIENT_CONF file and environment variables are not needed +# any more. +``` + +### Migration using the `Tee` implementation + +If your migration is more complex, or has special requirements, we also support +a 'tee' implementation of the topo service interface. It is defined in +`go/vt/topo/helpers/tee.go`. It allows communicating to two topo services, +and the migration uses multiple phases: + +* Start with the old topo service implementation we want to replace. +* Bring up the new topo service, with the same cells. +* Use `topo2topo` to copy the current data from the old to the new topo. +* Configure a Tee topo implementation to maintain both services. + * Note we don't expose a plugin for this, so a small code change is necessary. + * all updates will go to both services. + * the `primary` topo service is the one we will get errors from, if any. + * the `secondary` topo service is just kept in sync. + * at first, use the old topo service as `primary`, and the new one as + `secondary`. + * then, change the configuration to use the new one as `primary`, and the + old one as `secondary`. Reverse the lock order here. + * then rollout a configuration to just use the new service. diff --git a/content/zh/docs/19.0/user-guides/transport-security-model.md b/content/zh/docs/19.0/user-guides/transport-security-model.md new file mode 100644 index 000000000..3d7769358 --- /dev/null +++ b/content/zh/docs/19.0/user-guides/transport-security-model.md @@ -0,0 +1,72 @@ +--- +title: Transport Security Model +weight: 7 +--- + +Vitess exposes a few RPC services, and internally also uses RPCs. These RPCs may use secure transport options. This document explains how to use these features. + +## Overview + +The following diagram represents all the RPCs we use in a Vitess cluster: + +![Vitess Transport Security Model Diagram](../img/vitesstransportsecuritymodel.svg) + +There are two main categories: + +* Internal RPCs: they are used to connect Vitess components. +* Externally visible RPCs: they are use by the app to talk to Vitess. + +A few features in the Vitess ecosystem depend on authentication, like Caller ID and table ACLs. We'll explore the Caller ID feature first. + +The encryption and authentication scheme used depends on the transport used. With gRPC (the default for Vitess), TLS can be used to secure both internal and external RPCs. We'll detail what the options are. + +## Caller ID + +Caller ID is a feature provided by the Vitess stack to identify the source of queries. There are two different Caller IDs: + +* Immediate Caller ID: It represents the secure client identity when it enters the Vitess side: + - It is a single string, represents the user connecting to Vitess (vtgate). + - It is authenticated by the transport layer used. + - It is used by the Vitess TableACL feature. +* Effective Caller ID: It provides detailed information on who the individual caller process is: + - It contains more information about the caller: principal, component, sub-component. + - It is provided by the application layer. + - It is not authenticated. + - It is exposed in query logs to be able to debug the source of a slow query, for instance. + +## gRPC Transport + +### gRPC Encrypted Transport + +When using gRPC transport, Vitess can use the usual TLS security features (familiarity with SSL / TLS is necessary here): + +* Any Vitess server can be configured to use TLS with the following command line parameters: + - `grpc_cert`, `grpc_key`: server cert and key to use. + - `grpc_ca` (optional): client cert chains to trust. If specified, the client must use a certificate signed by one ca in the provided file. +* A Vitess go client can be configured with symmetrical parameters to enable TLS: + - `..._grpc_ca`: list of server cert signers to trust. + - `..._grpc_server_name`: name of the server cert to trust, instead of the hostname used to connect. + - `..._grpc_cert`, `..._grpc_key`: client side cert and key to use (when the server requires client authentication) +* Other clients can take similar parameters, in various ways, see each client for more information. + +With these options, it is possible to use TLS-secured connections for all parts of the system. This enables the server side to authenticate the client, and / or the client to authenticate the server. + +Note this is not enabled by default, as usually the different Vitess servers will run on a private network (in a Cloud environment, usually all local traffic is already secured over a VPN, for instance). + +### Certificates and Caller ID + +Additionally, if a client uses a certificate to connect to Vitess (vtgate), the common name of that certificate is passed to vttablet as the Immediate Caller ID. It can then be used by table ACLs, to grant read, write or admin access to individual tables. This should be used if different clients should have different access to Vitess tables. +Caller ID Override + +In a private network, where SSL security is not required, it might still be desirable to use table ACLs as a safety mechanism to prevent a user from accessing sensitive data. The gRPC connector provides the `grpc_use_effective_callerid` flag for this purpose: if specified when running vtgate, the Effective Caller ID's principal is copied into the Immediate Caller ID, and then used throughout the Vitess stack. + +**Important**: this is not secure. Any user code can provide any value for the Effective Caller ID's principal, and therefore access any data. This is intended as a safety feature to make sure some applications do not misbehave. Therefore, this flag is not enabled by default. +Example + +For a concrete example, see [test/encrypted_transport.py](https://github.com/vitessio/vitess/blob/master/test/encrypted_transport.py) in the source tree. It first sets up all the certificates, and some table ACLs, then uses the python client to connect with SSL. It also exercises the `grpc_use_effective_callerid` flag, by connecting without SSL. + +## MySQL Transport + +To get `vtgate` to support SSL/TLS use `-mysql_server_ssl_cert` and `-mysql_server_ssl_key`. + +To require client certificates set `-mysql_server_ssl_ca`. If there is no CA specified then TLS is optional. diff --git a/content/zh/docs/19.0/user-guides/upgrading.md b/content/zh/docs/19.0/user-guides/upgrading.md new file mode 100644 index 000000000..fdb78fe25 --- /dev/null +++ b/content/zh/docs/19.0/user-guides/upgrading.md @@ -0,0 +1,47 @@ +--- +title: Upgrading a Vitess Installation +weight: 8 +--- + +This document highlights things to look after when upgrading a Vitess production installation to a newer Vitess release. + +Generally speaking, upgrading Vitess is a safe and easy process because it is explicitly designed for it. This is because in YouTube we follow the practice of releasing new versions often (usually from the tip of the Git master branch). + +## Compatibility + +Our versioning strategy is based on [Semantic Versioning](http://semver.org/). + +Vitess version numbers follow the format `MAJOR.MINOR.PATCH`. We guarantee compatibility when upgrading to a newer **patch** or **minor** version. Upgrades to a higher **major** version may require manual configuration changes. + +In general, always **read the 'Upgrading' section of the release notes**. It will mention any incompatible changes and necessary manual steps. + +## Upgrade Order + +We recommend to upgrade components in a bottom-to-top order such that "old" clients will talk to "new" servers during the transition. + +Please use this upgrade order (unless otherwise noted in the release notes): + +* vttablet +* vtctld +* vtgate +* application code which links client libraries + +## Canary Testing + +Within the vtgate and vttablet components, we recommend to [canary](http://martinfowler.com/bliki/CanaryRelease.html) single instances, keyspaces and cells. Upgraded canary instances can "bake" for several hours or days to verify that the upgrade did not introduce a regression. Eventually, you can upgrade the remaining instances. + +## Rolling Upgrades + +We recommend to automate the upgrade process with a configuration management software. It will reduce the possibility of human errors and simplify the process of managing all instances. + +As of June 2016 we do not have templates for any major open-source configuration management software because our internal upgrade process is based on a proprietary software. Therefore, we invite open-source users to contribute such templates. + +Any upgrade should be a rolling release i.e. usually one tablet at a time within a shard. This ensures that the remaining tablets continue serving live traffic and there is no interruption. + +## Upgrading the Master Tablet + +The *master* tablet of each shard should always be updated last in the following manner: + +* verify that all *replica* tablets in the shard have been upgraded +* reparent away from the current *master* to a *replica* tablet +* upgrade old *master* tablet diff --git a/content/zh/docs/19.0/user-guides/vtexplain.md b/content/zh/docs/19.0/user-guides/vtexplain.md new file mode 100644 index 000000000..0e182d90f --- /dev/null +++ b/content/zh/docs/19.0/user-guides/vtexplain.md @@ -0,0 +1,153 @@ +--- +title: VTExplain +weight: 3 +--- + +## VTExplain Tool + +The vtexplain tool provides information about how Vitess will execute a statement (the Vitess version of MySQL "EXPLAIN"). + +## Prerequisites + +You'll need to build the `vtexplain` binary in your environment. To find instructions on how to build this binary please refer to this [guide](../../get-started/local). + +## Explaining a Query + +In order to explain a query you will need to first collect a sql schema for the various tables and a vschema json file containing a map of keyspace to the set of vindexes / tables in the vschema. + +For example, let's use the following: + +Schema: + +``` +CREATE TABLE users( + user_id bigint, + name varchar(128), + primary key(user_id) +); + +CREATE TABLE users_name_idx( + user_id bigint, + name varchar(128), + primary key(name, user_id) +); +``` + +VSchema: + +``` +{ + "mainkeyspace": { + "sharded": true, + "vindexes": { + "hash": { + "type": "hash" + }, + "md5": { + "type": "unicode_loose_md5", + "params": {}, + "owner": "" + }, + "users_name_idx": { + "type": "lookup_hash", + "params": { + "from": "name", + "table": "users_name_idx", + "to": "user_id" + }, + "owner": "users" + } + }, + "tables": { + "users": { + "column_vindexes": [ + { + "column": "user_id", + "name": "hash" + }, + { + "column": "name", + "name": "users_name_idx" + } + ], + "auto_increment": null + }, + "users_name_idx": { + "type": "", + "column_vindexes": [ + { + "column": "name", + "name": "md5" + } + ], + "auto_increment": null + } + } + } +} +``` + +These can be passed to vtexplain either on the command line or (more readily) through files. + +Then you can use the tool like this: + +**Select:** + +``` +vtexplain -shards 8 -vschema-file /tmp/vschema.json -schema-file /tmp/schema.sql -replication-mode "ROW" -output-mode text -sql "SELECT * from users" +---------------------------------------------------------------------- +SELECT * from users + +1 mainkeyspace/-20: select * from users limit 10001 +1 mainkeyspace/20-40: select * from users limit 10001 +1 mainkeyspace/40-60: select * from users limit 10001 +1 mainkeyspace/60-80: select * from users limit 10001 +1 mainkeyspace/80-a0: select * from users limit 10001 +1 mainkeyspace/a0-c0: select * from users limit 10001 +1 mainkeyspace/c0-e0: select * from users limit 10001 +1 mainkeyspace/e0-: select * from users limit 10001 + +---------------------------------------------------------------------- +``` + +The output shows the sequence of queries run. + +In this case, the query planner is a scatter query to all shards, and each line shows: + +(a) the logical sequence of the query (b) the keyspace/shard (c) the query that was executed + +The fact that each query runs at time 1 shows that vitess executes these in parallel, and the limit `10001` is automatically added as a protection against large results. + +**Insert:** + +``` +vtexplain -shards 128 -vschema-file /tmp/vschema.json -schema-file /tmp/schema.sql -replication-mode "ROW" -output-mode text -sql "INSERT INTO users (user_id, name) VALUES(1, 'john')" + +---------------------------------------------------------------------- +INSERT INTO users (user_id, name) VALUES(1, 'john') + +1 mainkeyspace/22-24: begin +1 mainkeyspace/22-24: insert into users_name_idx(name, user_id) values ('john', 1) /* vtgate:: keyspace_id:22c0c31d7a0b489a16332a5b32b028bc */ +2 mainkeyspace/16-18: begin +2 mainkeyspace/16-18: insert into users(user_id, name) values (1, 'john') /* vtgate:: keyspace_id:166b40b44aba4bd6 */ +3 mainkeyspace/22-24: commit +4 mainkeyspace/16-18: commit + +---------------------------------------------------------------------- +``` + +This example shows how Vitess handles an insert into a table with a secondary lookup vindex. + +First, at time `1`, a transaction is opened on one shard to insert the row into the `users_name_idx table`. Then at time `2` a second transaction is opened on another shard with the actual insert into the users table, and finally each transaction is committed at time `3` and `4`. + +**Configuration Options** + +The `--shards` option specifies the number of shards to simulate. vtexplain will always allocate an evenly divided key range to each. + +The `--replication-mode` option controls whether to simulate row based or statement based replication. + +You can find more usage of `vtexplain` by executing the following command: + +``` +vtexplain --help +``` diff --git a/content/zh/docs/19.0/user-guides/vttablet-modes.md b/content/zh/docs/19.0/user-guides/vttablet-modes.md new file mode 100644 index 000000000..f8041e90e --- /dev/null +++ b/content/zh/docs/19.0/user-guides/vttablet-modes.md @@ -0,0 +1,111 @@ +--- +title: VTTablet Modes +weight: 2 +--- + +VTTablet can be configured to control mysql at many levels. At the level with the most control, vttablet can perform backups and restores, respond to reparenting commands coming through vtctld, automatically fix replication, and enforce semi-sync settings. + +At the level with the least control, vttablet just sends the application’s queries to mysql. The level of desired control is achieved through various command line arguments, explained below. + +## Managed MySQL + +In the mode with the highest control, VTTablet can take backups. It can also automatically restore from an existing backup to prime a new replica. For this mode, vttablet needs to run on the same host as mysql, and must be given access to mysql's my.cnf file. Additionally, the flags must not contain any connectivity parameters like -db_host or -db_socket; VTTablet will fetch the socket information from my.cnf and use that to connect to the local mysql. + +It will also load other information from the my.cnf, like the location of data files, etc. When it receives a request to take a backup, it will shut down mysql, copy the mysql data files to the backup store, and restart mysql. + +The my.cnf file can be specified in the following ways: + +* Implicit: If mysql was initialized by the `mysqlctl` tool, then vttablet can find it based on just the `-tablet-path`. The default location for this file is `$VTDATAROOT/vt_/my.cnf`. +* `-mycnf-file`: This option can be used if the file is not present in the default location. +* `-my_cnf_server_id` and other flags: You can specify all values of the my.cnf file from the command line, and vttablet will behave as it read this information from a physical file. + +Specifying a` -db_host` or a `-db_socket` parameter will cause vttablet to skip the loading of the my.cnf file, and will disable its ability to perform backups or restores. + +## -restore_from_backup + +The default value for this flag is false. If set to true, and the my.cnf file was successfully loaded, then vttablet can perform automatic restores as follows: + +If started against a mysql instance that has no data files, it will search the list of backups for the latest one, and initiate a restore. After this, it will point the mysql to the current master and wait for replication to catch up. Once replication is caught up to the specified tolerance limit, it will advertise itself as serving. This will cause the vtgates to add it to the list of healthy tablets to serve queries from. + +If this flag is true, but my.cnf was not loaded, then vttablet will fatally exit with an error message. + +You can additionally control the level of concurrency for a restore with the `-restore_concurrency` flag. This is typically useful in cloud environments to prevent the restore process from becoming a 'noisy' neighbor by consuming all available disk IOPS. + +## Unmanaged or remote MySQL + +You can start a vttablet against a remote mysql by simply specifying the connection parameters `-db_host` and `-db_port` on the command line. In this mode, backup and restore operations will be disabled. If you start vttablet against a local mysql, you can specify a `-db_socket` instead, which will still make vttablet treat mysql as if it was remote. + +Specifically, the absence of a my.cnf file indicates to vttablet that it's connecting to a remote MySQL. + +## Partially managed MySQL + +Even if a MySQL is remote, you can still make vttablet perform some management functions. They are as follows: + +* `-disable_active_reparents`: If this flag is set, then any reparent or slave commands will not be allowed. These are InitShardMaster, PlannedReparent, PlannedReparent, EmergencyReparent, and ReparentTablet. In this mode, you should use the TabletExternallyReparented command to inform vitess of the current master. +* `-master_connect_retry`: This value is give to mysql when it connects a slave to the master as the retry duration parameter. +* `-enable_replication_reporter`: If this flag is set, then vttablet will transmit replica lag related information to the vtgates, which will allow it to balance load better. Additionally, enabling this will also cause vttablet to restart replication if it was stopped. However, it will do this only if -disable_active_reparents was not turned on. +* `-heartbeat_enable` and `-heartbeat interval duration`: cause vttablet to write heartbeats to the sidecar database. This information is also used by the replication reporter to assess replica lag. + +## Typical vttablet command line flags + +### Minimal vttablet to enable query serving + +``` +$TOPOLOGY_FLAGS +-tablet-path $alias +-init_keyspace $keyspace +-init_shard $shard +-init_tablet_type $tablet_type +-port $port +-grpc_port $grpc_port +-service_map 'grpc-queryservice,grpc-tabletmanager,grpc-updatestream' +``` + +`$alias` needs to be of the form: `-id`, and the cell should match one of the local cells that was created in the topology. The id can be left padded with zeroes: `cell-100` and `cell-000000100` are synonymous. + +Example `TOPOLOGY_FLAGS` for a lockserver like zookeeper: + +`-topo_implementation zk2 -topo_global_server_address localhost:21811,localhost:21812,localhost:21813 -topo_global_root /vitess/global` + +### Additional parameters to enable cluster management + +``` +-enable_replication_reporter +-backup_storage_implementation file +-file_backup_storage_root $BACKUP_MOUNT +-restore_from_backup +-vtctld_addr http://$hostname:$vtctld_web_port/ +``` + +### Additional parameters for running in prod + +``` +-queryserver-config-pool-size 24 +-queryserver-config-stream-pool-size 24 +-queryserver-config-transaction-cap 300 +``` + +More tuning parameters are available, but the above overrides are definitely needed for serving reasonable production traffic. + +### Connecting vttablet to an already running mysql + +``` +-db_host $MYSQL_HOST +-db_port $MYSQL_PORT +-db_app_user $USER +-db_app_password $PASSWORD +``` + +### Additional user credentials that need to be supplied for performing various operations + +``` +-db_allprivs_user +-db_allprivs_password +-db_appdebug_user +-db_appdebug_password +-db_dba_user +-db_dba_password +-db_filtered_user +-db_filtered_password +``` +Other flags exist for finer control.