vtexplain

<< vtctld vtgate >>

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.

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:

  1. 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:

  1. 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:

NameTypeDefinition
-output-modestringOutput in human-friendly text or json (default “text”)
-normalizeWhether to enable vtgate normalization (default false)
-shardsintNumber of shards per keyspace (default 2)
-replication-modestringThe replication mode to simulate – must be set to either ROW or STATEMENT (default “ROW”)
-schemastringThe SQL table schema (default “”)
-schema-filestringIdentifies the file that contains the SQL table schema (default “”)
-sqlstringA list of semicolon-delimited SQL commands to analyze (default “”)
-sql-filestringIdentifies the file that contains the SQL commands to analyze (default “”)
-vschemastringIdentifies the VTGate routing schema (default “”)
-vschema-filestringIdentifies the VTGate routing schema file (default “”)
-ks-shard-mapstringIdentifies the shard keyranges for unevenly-sharded keyspaces (default “”)
-ks-shard-map-filestringIdentifies the shard keyranges file (default “”)
-dbnamestringOptional database target to override normal routing (default “”)
-queryserver-config-passthrough-dmlsquery server pass through all dml statements without rewriting (default false)

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:

  1. "keyspace_name": {
  2.     "_comment": "Keyspace definition goes here."
  3. }

If no keyspace name is present, VTExplain will return the following error:

  1. ERROR: initVtgateExecutor: json: cannot unmarshal bool into Go value of type map[string]json.RawMessage

<< vtctld vtgate >>