Configuration Management Guide

This guide explains how to use MatrixOne’s comprehensive configuration management system to manage connection parameters, environment variables, and connection hooks.

Overview

MatrixOne provides a flexible configuration management system that allows you to:

• Set default connection parameters

• Override parameters via environment variables

• Configure connection hooks for automatic feature enablement

• Use different configuration formats for different use cases

• Debug and validate configurations

Basic Usage

Import the configuration functions:

from matrixone.config import get_connection_kwargs, print_config

Get default configuration:

# Get complete configuration
config = get_connection_kwargs()

# Print current configuration
print_config()

Environment Variables

You can override any configuration parameter using environment variables:

export MATRIXONE_HOST=localhost
export MATRIXONE_PORT=6001
export MATRIXONE_USER=admin
export MATRIXONE_PASSWORD=mypassword
export MATRIXONE_DATABASE=mydb
export MATRIXONE_ON_CONNECT=enable_all,enable_vector

Supported Environment Variables:

• MATRIXONE_HOST: Database host (default: 127.0.0.1)

• MATRIXONE_PORT: Database port (default: 6001)

• MATRIXONE_USER: Database user (default: root)

• MATRIXONE_PASSWORD: Database password (default: 111)

• MATRIXONE_DATABASE: Database name (default: test)

• MATRIXONE_CHARSET: Character set (default: utf8mb4)

• MATRIXONE_CONNECT_TIMEOUT: Connection timeout in seconds (default: 30)

• MATRIXONE_AUTOCOMMIT: Enable autocommit (default: True)

• MATRIXONE_ON_CONNECT: Connection hooks (comma-separated list)

Parameter Overrides

Override specific parameters in code:

from matrixone.config import get_connection_kwargs
from matrixone.connection_hooks import ConnectionAction

# Override specific parameters
config = get_connection_kwargs(
    host="production-server",
    port=6002,
    on_connect=[ConnectionAction.ENABLE_FULLTEXT]
)

Configuration Methods

MatrixOne provides three methods for getting configuration:

1. get_config() - Returns complete configuration dictionary

2. get_connection_params() - Returns core parameters as tuple

3. get_connection_kwargs() - Returns all parameters as dictionary

from matrixone.config import get_config, get_connection_params, get_connection_kwargs

# Get complete configuration
config = get_config()

# Get core parameters as tuple
host, port, user, password, database = get_connection_params()

# Get all parameters as dictionary (most commonly used)
kwargs = get_connection_kwargs()

Using with Client

Connect using configuration:

from matrixone import Client
from matrixone.config import get_connection_kwargs

# Get configuration
config = get_connection_kwargs()

# Filter to only supported parameters for Client.connect()
client = Client()
client.connect(
    host=config['host'],
    port=config['port'],
    user=config['user'],
    password=config['password'],
    database=config['database'],
    on_connect=config['on_connect']
)

Connection Hooks Configuration

Configure connection hooks for automatic feature enablement:

from matrixone.config import get_connection_kwargs
from matrixone.connection_hooks import ConnectionAction, create_connection_hook

# Using predefined actions
config = get_connection_kwargs(
    on_connect=[ConnectionAction.ENABLE_ALL]
)

# Using string names
config = get_connection_kwargs(
    on_connect=["enable_fulltext", "enable_vector"]
)

# Using custom callback
def my_callback(client):
    print(f"Connected to {client._connection_params['host']}")

config = get_connection_kwargs(on_connect=my_callback)

# Using mixed actions and callbacks
config = get_connection_kwargs(
    on_connect=create_connection_hook(
        actions=[ConnectionAction.ENABLE_FULLTEXT],
        custom_hook=my_callback
    )
)

Environment Variable for Connection Hooks

Set connection hooks via environment variable:

# Enable all features
export MATRIXONE_ON_CONNECT=enable_all

# Enable specific features
export MATRIXONE_ON_CONNECT=enable_ivf,enable_hnsw,enable_fulltext

# Multiple actions
export MATRIXONE_ON_CONNECT=enable_vector,enable_fulltext

Configuration Debugging

Debug and validate configurations:

from matrixone.config import print_config

# Print current configuration
print_config()

# Print configuration with overrides
print_config(host="test-server", port=6003)

Output example:

MatrixOne Connection Configuration:
========================================
  host: 127.0.0.1
  port: 6001
  user: root
  password: ***
  database: test
  charset: utf8mb4
  connect_timeout: 30
  autocommit: True
  on_connect: None
========================================

Advanced Usage

Class-based Configuration

Use the MatrixOneConfig class directly:

from matrixone.config import MatrixOneConfig

# Get configuration with environment overrides
config = MatrixOneConfig.get_config()

# Get connection parameters as tuple
host, port, user, password, database = MatrixOneConfig.get_connection_params()

# Get connection parameters as keyword arguments
kwargs = MatrixOneConfig.get_connection_kwargs()

# Print current configuration
MatrixOneConfig.print_config()

Configuration Precedence

Configuration parameters are applied in the following order:

1. Default configuration

2. Environment variable overrides

3. Direct parameter overrides

Later values override earlier ones.

Best Practices

1. Use Environment Variables for Deployment Set environment variables in your deployment environment rather than hardcoding values.

2. Use get_connection_kwargs() for Most Cases This method provides the most comprehensive configuration.

3. Filter Parameters for Client.connect() Only pass supported parameters to avoid errors.

4. Use Connection Hooks for Feature Enablement Configure connection hooks to automatically enable features like vector operations and fulltext search.

5. Debug with print_config() Use print_config() to verify your configuration before connecting.

Example Applications

Production Setup

from matrixone import Client
from matrixone.config import get_connection_kwargs

# Production configuration via environment variables
config = get_connection_kwargs()

# Filter to supported parameters
client = Client()
client.connect(
    host=config['host'],
    port=config['port'],
    user=config['user'],
    password=config['password'],
    database=config['database'],
    on_connect=config['on_connect']
)

Development Setup

from matrixone import Client
from matrixone.config import get_connection_kwargs
from matrixone.connection_hooks import ConnectionAction

# Development configuration with overrides
config = get_connection_kwargs(
    host="localhost",
    database="dev_db",
    on_connect=[ConnectionAction.ENABLE_ALL]
)

client = Client()
client.connect(
    host=config['host'],
    port=config['port'],
    user=config['user'],
    password=config['password'],
    database=config['database'],
    on_connect=config['on_connect']
)

Testing Setup

from matrixone import Client
from matrixone.config import get_connection_kwargs

# Test configuration
config = get_connection_kwargs(
    database="test_db",
    on_connect=None  # No hooks for testing
)

client = Client()
client.connect(
    host=config['host'],
    port=config['port'],
    user=config['user'],
    password=config['password'],
    database=config['database']
)

API Reference

MatrixOne Configuration Management

This module provides comprehensive configuration management for MatrixOne connections, allowing users to override default connection parameters via environment variables, configuration files, or direct parameter overrides.

Features:

• Default connection parameters with sensible defaults

• Environment variable overrides for all connection parameters

• Support for connection hooks via on_connect parameter

• Multiple configuration retrieval methods (tuple, dict, kwargs)

• Configuration debugging and validation

Usage Examples:

from matrixone.config import get_connection_kwargs, print_config
from matrixone.connection_hooks import ConnectionAction
from matrixone import Client

# Basic Configuration
config = get_connection_kwargs()
print_config()

# Parameter Overrides
config = get_connection_kwargs(
    host="production-server",
    port=6002,
    on_connect=[ConnectionAction.ENABLE_FULLTEXT]
)

# Using with Client
client = Client()
client.connect(**config)

Environment Variables:

• MATRIXONE_HOST: Database host (default: 127.0.0.1)

• MATRIXONE_PORT: Database port (default: 6001)

• MATRIXONE_USER: Database user (default: root)

• MATRIXONE_PASSWORD: Database password (default: 111)

• MATRIXONE_DATABASE: Database name (default: test)

• MATRIXONE_CHARSET: Character set (default: utf8mb4)

• MATRIXONE_CONNECT_TIMEOUT: Connection timeout in seconds (default: 30)

• MATRIXONE_AUTOCOMMIT: Enable autocommit (default: True)

• MATRIXONE_ON_CONNECT: Connection hooks (comma-separated list)

Connection Hooks:

The on_connect parameter supports:

• Predefined actions: enable_all, enable_ivf, enable_hnsw, enable_fulltext, enable_vector

• Custom callback functions

• Mixed actions and callbacks

Example on_connect values: “enable_all”, “enable_ivf,enable_hnsw”, or custom function

class matrixone.config.MatrixOneConfig

Bases: object

MatrixOne connection configuration manager.

This class provides centralized configuration management for MatrixOne connections, supporting environment variable overrides, parameter validation, and multiple output formats for different use cases.

Attributes:

DEFAULT_CONFIG (Dict[str, Any]): Default connection parameters
ENV_MAPPING (Dict[str, str]): Mapping of parameters to environment variables

Example:

# Get configuration with environment overrides
config = MatrixOneConfig.get_config()

# Get connection parameters as tuple
host, port, user, password, database = MatrixOneConfig.get_connection_params()

# Get connection parameters as keyword arguments
kwargs = MatrixOneConfig.get_connection_kwargs()

# Print current configuration
MatrixOneConfig.print_config()

DEFAULT_CONFIG = {'autocommit': True, 'charset': 'utf8mb4', 'connect_timeout': 30, 'database': 'test', 'host': '127.0.0.1', 'on_connect': None, 'password': '111', 'port': 6001, 'user': 'root'}

ENV_MAPPING = {'autocommit': 'MATRIXONE_AUTOCOMMIT', 'charset': 'MATRIXONE_CHARSET', 'connect_timeout': 'MATRIXONE_CONNECT_TIMEOUT', 'database': 'MATRIXONE_DATABASE', 'host': 'MATRIXONE_HOST', 'on_connect': 'MATRIXONE_ON_CONNECT', 'password': 'MATRIXONE_PASSWORD', 'port': 'MATRIXONE_PORT', 'user': 'MATRIXONE_USER'}

classmethod get_config(**overrides) → Dict[str, Any]

Get connection configuration with environment variable overrides.

This method retrieves the complete configuration dictionary, applying environment variable overrides and direct parameter overrides in order: 1. Default configuration 2. Environment variable overrides 3. Direct parameter overrides

Args:

**overrides: Additional parameter overrides. These take precedence
            over environment variables and defaults.

Returns:

Dict[str, Any]: Complete configuration dictionary containing:
    - host (str): Database host
    - port (int): Database port
    - user (str): Database user
    - password (str): Database password
    - database (str): Database name
    - charset (str): Character set
    - connect_timeout (int): Connection timeout in seconds
    - autocommit (bool): Enable autocommit
    - on_connect (Any): Connection hooks configuration

Example:

# Get default configuration
config = MatrixOneConfig.get_config()

# Override specific parameters
config = MatrixOneConfig.get_config(
    host="production-server",
    port=6002,
    on_connect=[ConnectionAction.ENABLE_ALL]
)

classmethod get_connection_params(**overrides) → tuple

Get connection parameters as tuple for easy unpacking.

This method returns the core connection parameters as a tuple, which is useful for direct unpacking into function calls.

Args:

**overrides: Additional parameter overrides

Returns:

Tuple[str, int, str, str, str]: Tuple containing (host, port, user, password, database)

Example:

# Unpack parameters directly
host, port, user, password, database = MatrixOneConfig.get_connection_params()

# Use with legacy connection methods
connection = create_connection(*MatrixOneConfig.get_connection_params())

classmethod get_connection_kwargs(**overrides) → Dict[str, Any]

Get connection parameters as keyword arguments.

This method returns all connection parameters as a dictionary, including extended parameters like charset, timeout, and connection hooks. This is the most comprehensive configuration method.

Args:

**overrides: Additional parameter overrides

Returns:

Dict[str, Any]: Complete connection parameters dictionary

Example:

from matrixone import Client
from matrixone.connection_hooks import ConnectionAction

# Get complete configuration and use directly with Client constructor
client = Client(**MatrixOneConfig.get_connection_kwargs(
    on_connect=[ConnectionAction.ENABLE_ALL]
))

# Or use with connect method
config = MatrixOneConfig.get_connection_kwargs()
client = Client()
client.connect(
    host=config['host'],
    port=config['port'],
    user=config['user'],
    password=config['password'],
    database=config['database'],
    charset=config['charset'],
    on_connect=config['on_connect']
)

classmethod print_config(**overrides)

Print current configuration for debugging and validation.

This method displays the current configuration in a formatted way, showing all parameters with their current values. Sensitive information like passwords are masked for security.

Args:

**overrides: Additional parameter overrides to apply before printing

Example:

# Print default configuration
MatrixOneConfig.print_config()

# Print configuration with overrides
MatrixOneConfig.print_config(host="production-server", port=6002)

Note: Prints formatted configuration to stdout.

matrixone.config.get_config(**overrides) → Dict[str, Any]

Get MatrixOne connection configuration.

Convenience function for MatrixOneConfig.get_config().

Args:

**overrides: Additional parameter overrides

Returns:

Dict[str, Any]: Complete configuration dictionary

Example:

from matrixone.config import get_config

config = get_config(host="production-server")

matrixone.config.get_connection_params(**overrides) → tuple

Get MatrixOne connection parameters as tuple.

Convenience function for MatrixOneConfig.get_connection_params().

Args:

**overrides: Additional parameter overrides

Returns:

Tuple[str, int, str, str, str]: Connection parameters tuple

Example:

from matrixone.config import get_connection_params

host, port, user, password, database = get_connection_params()

matrixone.config.get_connection_kwargs(**overrides) → Dict[str, Any]

Get MatrixOne connection parameters as keyword arguments.

Convenience function for MatrixOneConfig.get_connection_kwargs(). This is the most commonly used function for getting complete configuration.

Args:

**overrides: Additional parameter overrides

Returns:

Dict[str, Any]: Complete connection parameters dictionary

Example:

from matrixone.config import get_connection_kwargs
from matrixone.connection_hooks import ConnectionAction

config = get_connection_kwargs(on_connect=[ConnectionAction.ENABLE_ALL])

matrixone.config.get_client_kwargs(**overrides) → Dict[str, Any]

Get connection parameters suitable for Client constructor.

This method returns connection parameters that can be directly passed to the Client() constructor, excluding parameters that are only used by the connect() method.

Args:

**overrides: Additional parameter overrides

Returns:

Dict[str, Any]: Client constructor parameters dictionary

Example:

from matrixone import Client
from matrixone.config import get_client_kwargs

# Create client with all configuration in one line
client = Client(**get_client_kwargs())

# Or with overrides
client = Client(**get_client_kwargs(host="production-server"))

matrixone.config.print_config(**overrides)

Print current MatrixOne configuration.

Convenience function for MatrixOneConfig.print_config().

Args:

**overrides: Additional parameter overrides to apply before printing

Example:

from matrixone.config import print_config

print_config()  # Print current configuration

Related Topics

• Connection Hooks Guide - Learn about connection hooks

• Quick Start - Get started with MatrixOne

• Best Practices Guide - Best practices for MatrixOne usage