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:

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:

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:

--output-modestringOutput in human-friendly text or json (default "text")
--planner-versionstringSets the query planner version to use when generating the explain output. Valid values are V3 and Gen4 (default "Gen4")
--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:

"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