From 3d8a350cbf69bb8f3757eeb1facf15afe9b2faf1 Mon Sep 17 00:00:00 2001 From: Max Englander Date: Sun, 4 Dec 2022 19:18:59 -0500 Subject: [PATCH] document global keyspace flag Signed-off-by: Max Englander --- .../16.0/reference/features/global-routing.md | 95 +++++++++++++++++-- .../en/docs/16.0/reference/programs/vtgate.md | 1 + 2 files changed, 89 insertions(+), 7 deletions(-) diff --git a/content/en/docs/16.0/reference/features/global-routing.md b/content/en/docs/16.0/reference/features/global-routing.md index 1100bd907..635dfeaf5 100644 --- a/content/en/docs/16.0/reference/features/global-routing.md +++ b/content/en/docs/16.0/reference/features/global-routing.md @@ -4,12 +4,32 @@ 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](https://vitess.io/docs/concepts/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 share a name with an explicitly specified `source` table. +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. + +## Requirements + +Vitess will globally route queries for tables when: + + * They are specified in the VSchema, + * And either: + * They have a globally unique name, + * Or they are [Reference Tables](../../../user-guides/vschema-guide/advanced-vschema/#reference-tables) with a `source`, + * And either: + * The connection does not use a default keyspace, + * Or the connection uses a Global Keyspace, + * Or the table is name is qualified with a Global Keyspace. + +## Global Keyspaces + +Global keyspaces are a feature that enables global routing to be requested by using a global keyspace name in the connection, or by qualifying a query by a global keyspace name. + +To enable this feature, set one or more [VTGate `--global-keyspace [global_ks]` flags](../../programs/vtgate/#options). + +## Examples + +Given keyspaces `ks`, `customer` and `commerce`: -Example: ```sql mysql> show keyspaces; +----------+ @@ -22,7 +42,7 @@ mysql> show keyspaces; 3 rows in set (0.00 sec) ``` -`ks` and `customer` are sharded keyspaces and `commerce` is an unsharded keyspace. +`ks` and `customer` are sharded keyspaces, and `commerce` is an unsharded keyspace. Tables present in each of the keyspace. @@ -57,6 +77,10 @@ mysql> show tables from commerce; 3 rows in set (0.00 sec) ``` +
+ +#### Without a default keyspace + Without a default keyspace we can route to unique tables like `corder`, `product` and `player` but cannot route to `customer` ```sql @@ -94,7 +118,12 @@ 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`. +
+ +#### With a default keyspace + +With the default keyspace set to `customer` we can only query keyspace-unqualified tables in `commerce` i.e `customer` and `corder`. + ```sql mysql> use customer Reading table information for completion of table and column names @@ -125,7 +154,12 @@ 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. +
+ +#### Queries qualified by a keyspace + +With a default keyspace set, queries can be routed to other keyspaces by qualifying the table name with the keyspace name. + ```sql mysql> use customer Reading table information for completion of table and column names @@ -151,3 +185,50 @@ mysql> show columns from commerce.product; +-------------+----------------+------+-----+---------+-------+ 3 rows in set (0.00 sec) ``` + +
+ +#### With a default global keyspace + +Global routing may be requested by using a global keyspace on the connection. Vitess will behave the same way as if no default keyspace was set. + +```sql +mysql> use global_ks; +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 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) +``` + +
+ +#### Queries qualified by a global keyspace + +With a default keyspace set, global routing may be requested by qualifying a table with a global keyspace. + +```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 global_ks.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/16.0/reference/programs/vtgate.md b/content/en/docs/16.0/reference/programs/vtgate.md index 800d3762e..97f998e9d 100644 --- a/content/en/docs/16.0/reference/programs/vtgate.md +++ b/content/en/docs/16.0/reference/programs/vtgate.md @@ -59,6 +59,7 @@ The following global options apply to `vtgate`: | --enable_set_var | boolean | This will enable the use of MySQL's SET_VAR query hint for certain system variables instead of using reserved connections. | | --gate_query_cache_size | int | gate server query cache size, maximum number of queries 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 10000) | | --gateway_initial_tablet_timeout | duration | At startup, the gateway will wait up to that duration to get one tablet per keyspace/shard/tablettype (default 30s) | +| --global-keyspace | strings | Global routing behavior applies when no default keyspace is set on a connection, or when a global keyspace is used. Multiple global keyspaces may defined by specifying this flag multiple times. | | --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 |