CLI Tools

This module provides interactive diagnostic tools for MatrixOne database administration and maintenance.

MatrixOneCLI Class

class matrixone.cli_tools.MatrixOneCLI(client: Client | None = None)[source]

Bases: Cmd

Interactive CLI for MatrixOne diagnostics

Interactive command-line interface for MatrixOne diagnostics.

The MatrixOneCLI class provides a comprehensive set of commands for:

Index inspection and verification
Vector index (IVF/HNSW) status monitoring
Table statistics and metadata analysis
Database operations (flush, connect, etc.)
SQL query execution

Available Commands:

Connection Management:

connect <host> <port> <user> <password> [database] - Connect to database
use <database> - Switch database
databases - List all databases
tables [database] - List tables

Index Inspection:

show_indexes <table> [database] - Show all indexes for a table
show_all_indexes [database] - Health report for all tables with indexes
verify_counts <table> [database] - Verify row count consistency
show_ivf_status [database] [-v] [-t table] - Show IVF index status

Table Statistics:

show_table_stats <table> [database] [-t] [-a] [-d] - Show table statistics

Operations:

flush_table <table> [database] - Flush table and indexes (requires sys)
sql <query> - Execute SQL query

Utilities:

history [n] - Show command history
help [command] - Show help
exit / quit - Exit tool

Example Usage:

from matrixone import Client
from matrixone.cli_tools import MatrixOneCLI

# Create client and CLI
client = Client()
client.connect(host='localhost', port=6001, user='root', password='111', database='test')

cli = MatrixOneCLI(client)

# Execute commands programmatically
cli.onecmd("show_all_indexes")
cli.onecmd("show_ivf_status -v")
cli.onecmd("show_table_stats documents -a")

# Or start interactive mode
cli.cmdloop()

intro = '\n╔══════════════════════════════════════════════════════════════╗\n║ MatrixOne Interactive Diagnostic Tool ║\n║ ║\n║ Type help or ? to list commands. ║\n║ Type help <command> for detailed help on a command. ║\n║ ║\n║ Tips: ║\n║ • Press Tab for auto-completion (tables/databases) ║\n║ • Use ↑/↓ arrows to browse command history ║\n║ • Press Ctrl+R for history search ║\n╚══════════════════════════════════════════════════════════════╝\n'

__init__(client: Client | None = None)[source]

Initialize the CLI tool.

Parameters:: client – Optional MatrixOne client. If not provided, you’ll need to connect manually.

prompt = 'MO-DIAG> '

cmdloop(intro=None)[source]: Override cmdloop to use prompt_toolkit for better input experience

do_connect(arg)[source]

Connect to MatrixOne database.

Usage: connect <host> <port> <user> <password> [database] Example: connect localhost 6001 root 111 test

do_use(arg)[source]

Switch to a different database.

Usage: use <database> Example: use test

do_show_indexes(arg)[source]

Show all secondary indexes for a table, including IVF, HNSW, Fulltext, and regular indexes.

Uses vertical output format (like MySQL G) for easy reading of long table names.

Usage: show_indexes <table_name> [database]

Example

show_indexes cms_all_content_chunk_info show_indexes cms_all_content_chunk_info repro3

do_show_all_indexes(arg)[source]

Show index health report for all tables with secondary indexes.

This command performs diagnostic checks including: - Row count consistency between main table and index tables - Vector index building status (IVF/HNSW) - Index type distribution - Problem detection

Usage: show_all_indexes [database] .. rubric:: Example

show_all_indexes show_all_indexes repro3

do_cdc_health(arg)[source]

Check CDC task health, including error states and watermark lag.

Usage: cdc_health [threshold] [–task=<task_name>] [–threshold=<duration>] [–strict] [–details] .. rubric:: Example

cdc_health cdc_health 5 cdc_health –task=cdc_sales_sync –threshold=15 cdc_health –strict cdc_health –details

When a numeric threshold or --threshold is provided, it overrides the default 10 minute tolerance used to detect late watermarks. --strict applies a zero minute tolerance (useful for quick smoke checks).

do_cdc_task(arg)[source]

Inspect a specific CDC task, optionally pausing/resuming and reviewing per-table watermarks.

Usage:: cdc_task <task_name> [–details] [–no-watermarks] [–watermarks-only] [–table=<name>] [–threshold=<duration>] [–strict] [–pause|–resume|–restart]

Examples

cdc_task cdc_orders_sync cdc_task cdc_orders_sync –details –table=orders cdc_task cdc_orders_sync –pause cdc_task cdc_orders_sync –threshold=5 –strict

do_cdc_tasks(arg)[source]

List CDC tasks and basic metadata.

Usage:: cdc_tasks [–details]

Example

cdc_tasks cdc_tasks –details

do_cdc_create(arg)[source]

Guided helper to create a CDC task.

Usage:: cdc_create [–database-level|–table-level]

If no level flag is supplied, you will be prompted to choose between database-level and table-level replication.

do_cdc_drop(arg)[source]

Drop a CDC task with double confirmation.

Usage:: cdc_drop <task_name> [–force]

The command will prompt for confirmation twice unless --force is supplied.

do_verify_counts(arg)[source]

Verify row counts between main table and all its index tables.

Usage: verify_counts <table_name> [database] .. rubric:: Example

verify_counts cms_all_content_chunk_info verify_counts cms_all_content_chunk_info repro3

do_show_ivf_status(arg)[source]

Show IVF index centroids building status.

Usage:: show_ivf_status [database] - Show compact summary show_ivf_status [database] -v - Show detailed view show_ivf_status [database] -t table - Filter by table name

Example

show_ivf_status show_ivf_status test -v show_ivf_status test -t my_table

do_show_table_stats(arg)[source]

Show table statistics using metadata_scan.

Usage:: show_table_stats <table> [database] - Show table stats summary show_table_stats <table> [database] -t - Include tombstone stats show_table_stats <table> [database] -i idx1,idx2 - Include specific index stats show_table_stats <table> [database] -a - Include all (tombstone + all indexes) show_table_stats <table> [database] -d - Show detailed object list

Example

show_table_stats my_table show_table_stats my_table test -t show_table_stats my_table test -i idx_vec,idx_name show_table_stats my_table test -a show_table_stats my_table test -a -d

do_flush_table(arg)[source]

Flush table and all its secondary index tables

Usage:: flush_table <table> [database] - Flush main table and all its index tables

Example

flush_table my_table flush_table my_table test

Note: Requires sys user privileges

do_tables(arg)[source]

Show all tables in current database or specified database

Usage:: tables - Show all tables in current database tables <database> - Show all tables in specified database

Example

tables tables test

do_databases(arg)[source]

Show all databases

Usage:: databases - Show all databases

Example

databases

do_history(arg)[source]

Show command history

Usage:: history - Show last 20 commands history <n> - Show last n commands history -c - Clear history

Example

history history 50 history -c

do_sql(arg)[source]

Execute a SQL query directly.

Usage: sql <SQL statement> Example: sql SELECT COUNT(*) FROM cms_all_content_chunk_info

do_exit(arg)[source]: Exit the interactive tool.

do_quit(arg)[source]: Exit the interactive tool.

do_EOF(arg)[source]: Handle Ctrl+D to exit.

emptyline()[source]: Do nothing on empty line.

Helper Functions

matrixone.cli_tools.start_interactive_tool(host='localhost', port=6001, user='root', password='111', database=None, log_level='ERROR')[source]

Start the interactive diagnostic tool.

Parameters:

host – Database host
port – Database port
user – Database user
password – Database password
database – Database name (optional)
log_level – Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: ERROR

Start the interactive diagnostic tool with connection parameters.

Parameters:

host (str): Database host (default: ‘localhost’)
port (int): Database port (default: 6001)
user (str): Database user (default: ‘root’)
password (str): Database password (default: ‘111’)
database (str): Database name (optional)
log_level (str): Logging level (default: ‘ERROR’)

Example:

from matrixone.cli_tools import start_interactive_tool

# Start interactive tool
start_interactive_tool(
    host='localhost',
    port=6001,
    user='root',
    password='111',
    database='test',
    log_level='ERROR'
)

matrixone.cli_tools.main_cli()[source]

Main entry point for the CLI tool when installed via pip. This function is called when running ‘mo-diag’ command.

Supports both interactive and non-interactive modes: - Interactive: mo-diag (enters interactive shell) - Non-interactive: mo-diag -c “show_ivf_status test” (executes single command and exits)

Main entry point for the mo-diag command-line tool.

This function is called when running mo-diag from the command line. It supports both interactive and non-interactive modes.

Command-Line Options:

mo-diag [options]

Options:
  --host HOST           Database host (default: localhost)
  --port PORT           Database port (default: 6001)
  --user USER           Database user (default: root)
  --password PASSWORD   Database password (default: 111)
  --database DATABASE   Database name (optional)
  -d DATABASE           Short form of --database
  --log-level LEVEL     Logging level (default: ERROR)
  --command COMMAND     Execute single command and exit
  -c COMMAND            Short form of --command

Sub-commands:
  cdc                   Manage CDC tasks (show/create/drop helpers)

Examples:

# Interactive mode
mo-diag --database test

# Non-interactive mode - execute single command
mo-diag -d test -c "show_ivf_status"
mo-diag -d test -c "show_table_stats my_table -a"

# CDC management helpers
mo-diag cdc show
mo-diag cdc show nightly_sync --details --threshold=5m
mo-diag cdc create --table-level
mo-diag cdc drop nightly_sync --force

Utility Functions

matrixone.cli_tools.success(msg)[source]

Print success message in green

Format success message in green color.

matrixone.cli_tools.error(msg)[source]

Print error message in red

Format error message in red color.

matrixone.cli_tools.warning(msg)[source]

Print warning message in yellow

Format warning message in yellow color.

matrixone.cli_tools.info(msg)[source]

Print info message in cyan

Format info message in cyan color.

matrixone.cli_tools.bold(msg)[source]

Print message in bold

Format message in bold text.

matrixone.cli_tools.header(msg)[source]

Print header in bold cyan

Format header in bold cyan.

Colors Class

class matrixone.cli_tools.Colors[source]

ANSI color codes

ANSI color codes for terminal output formatting.

Attributes:

RESET - Reset all formatting
BOLD - Bold text
RED - Red foreground
GREEN - Green foreground
YELLOW - Yellow foreground
BLUE - Blue foreground
MAGENTA - Magenta foreground
CYAN - Cyan foreground
WHITE - White foreground

Methods:

static disable()[source]

Disable colors (for non-terminal output)

Disable all colors (for non-terminal output).

RESET = ''

BOLD = ''

RED = ''

GREEN = ''

YELLOW = ''

BLUE = ''

MAGENTA = ''

CYAN = ''

WHITE = ''

BG_RED = ''

BG_GREEN = ''

BG_YELLOW = ''

static disable()[source]: Disable colors (for non-terminal output)

MODiagCompleter Class

class matrixone.cli_tools.MODiagCompleter(cli_instance)[source]

Bases: Completer

Smart completer for mo-diag commands that provides table and database name completion

Smart completer for mo-diag commands that provides table and database name completion.

This completer integrates with prompt_toolkit to provide:

Command name completion
Table name completion for relevant commands
Database name completion
Context-aware suggestions

Features:

Auto-completes command names
Auto-completes table names from current database
Auto-completes database names
Context-aware based on command type

get_completions(document, complete_event)[source]: Generate completions based on current input

__init__(cli_instance)[source]

CLI Tools

MatrixOneCLI Class

Helper Functions

Utility Functions

Colors Class

MODiagCompleter Class

See Also