MoCtl Manager

This section documents the mo_ctl management classes that provide programmatic access to MatrixOne control operations.

MoCtlManager

class matrixone.moctl.MoCtlManager(client)

Bases: object

Manager for MatrixOne control operations (mo_ctl).

This class provides access to MatrixOne’s control operations through the mo_ctl SQL function. It allows programmatic execution of various MatrixOne administrative and maintenance operations.

⚠️ CRITICAL REQUIREMENT: All mo_ctl operations require ‘sys’ account privileges. These operations cannot be executed with regular user accounts.

Key Features:

• Programmatic access to mo_ctl commands

• Table flush operations for data persistence

• Checkpoint operations for data consistency

• Integration with MatrixOne client operations

• Error handling and result parsing

Supported Operations:

• Table flush operations (flush_table)

• Incremental checkpoints (increment_checkpoint)

• Global checkpoints (global_checkpoint)

Usage Examples:

# IMPORTANT: Connect with sys account first client = Client() client.connect(host, port, ‘sys#root’, password, database)

# Initialize mo_ctl manager moctl = client.moctl

# Flush a specific table result = moctl.flush_table(“database_name”, “table_name”)

# Force incremental checkpoint result = moctl.increment_checkpoint()

# Force global checkpoint result = moctl.global_checkpoint()

Requirements: - Must connect with ‘sys’ account (e.g., ‘sys#root’ or account=’sys’) - Requires appropriate administrative privileges - Operations may require specific tenant permissions

Note: If you get permission errors, ensure you’re connected with sys account:

client.connect(host, port, ‘sys#root’, password, database) # or client.connect(host, port, ‘root’, password, database, account=’sys’)

__init__(client)

Initialize MoCtlManager

Parameters:

client – MatrixOne client instance

flush_table(database: str, table: str) → Dict[str, Any]

Force flush table.

Force flush table table in database database. It returns after all blks in the table are flushed.

⚠️ Requires ‘sys’ account privileges.

Parameters:

• database – Database name

• table – Table name

Returns:

Result of the flush operation

Example

>>> client.moctl.flush_table('db1', 't')
{'method': 'Flush', 'result': [{'returnStr': 'OK'}]}

increment_checkpoint() → Dict[str, Any]

Force incremental checkpoint.

Flush all blks in DN, generate an Incremental Checkpoint and truncate WAL.

⚠️ Requires ‘sys’ account privileges.

Returns:

Result of the incremental checkpoint operation

Example

>>> client.moctl.increment_checkpoint()
{'method': 'Checkpoint', 'result': [{'returnStr': 'OK'}]}

global_checkpoint() → Dict[str, Any]

Force global checkpoint.

Generate a global checkpoint across all nodes.

⚠️ Requires ‘sys’ account privileges.

Returns:

Result of the global checkpoint operation

Example

>>> client.moctl.global_checkpoint()
{'method': 'GlobalCheckpoint', 'result': [{'returnStr': 'OK'}]}