define

mcp_ohmy_sql Configuration System

This module defines the configuration system for the mcp_ohmy_sql MCP server, providing a flexible JSON-based configuration that supports multiple databases and schemas.

The configuration system is built on Pydantic models for validation and type safety, ensuring robust configuration handling for production deployments.

class mcp_ohmy_sql.config.define.Settings

Global settings for the MCP server.

This class is currently empty but reserved for future global configuration options such as query timeout limits, result size limits, logging levels, and other server-wide settings.

Example:

In JSON configuration:

{
    "settings": {}
}

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcp_ohmy_sql.config.define.TableFilter(*, include: list[str] = <factory>, exclude: list[str] = <factory>)

Table filtering configuration for database schemas.

Provides include/exclude patterns to control which tables are accessible through the MCP server. Supports wildcards for flexible filtering.

Parameters:

• include – List of table names or patterns to include. If empty, includes all tables not in exclude list. Supports wildcards with ‘*’.

• exclude – List of table names or patterns to exclude. Supports wildcards with ‘*’. Applied after include filtering.

Examples:

Include specific tables only:

{
    "include": ["users", "orders", "products"],
    "exclude": []
}

Exclude system and temporary tables:

{
    "include": [],
    "exclude": ["pg_*", "information_schema", "tmp_*", "_backup_*"]
}

Mixed filtering:

{
    "include": ["sales_*", "customer_*"],
    "exclude": ["*_temp", "*_staging"]
}

Note

When both include and exclude are specified, tables must be in the include list AND not in the exclude list to be accessible.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcp_ohmy_sql.config.define.Schema(*, name: str | None = None, table_filter: ~mcp_ohmy_sql.config.define.TableFilter = <factory>)

Database schema configuration.

Defines a specific schema within a database and its table filtering rules. Each database can have multiple schemas, allowing fine-grained control over which parts of the database are accessible.

Parameters:

• name – Schema name. If None, uses the database’s default schema. Some databases (like SQLite) don’t have explicit schemas.

• table_filter – TableFilter rules for this schema.

Examples:

Default schema with filtering:

{
    "table_filter": {
        "exclude": ["_migrations", "temp_*"]
    }
}

Named schema with specific tables:

{
    "name": "reporting",
    "table_filter": {
        "include": ["sales_summary", "customer_metrics"],
        "exclude": []
    }
}

Multiple schemas for different purposes:

[
    {
        "name": "public",
        "table_filter": {"exclude": ["audit_*"]}
    },
    {
        "name": "analytics",
        "table_filter": {"include": ["fact_*", "dim_*"]}
    }
]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcp_ohmy_sql.config.define.Database(*, identifier: str, description: str = '', db_type: str, connection: SqlalchemyConnection | AWSRedshiftConnection, schemas: list[Schema])

Database configuration definition.

Represents a single database connection with its schemas and access rules. Each database must have a unique identifier and can contain multiple schemas with different filtering rules.

Parameters:

• identifier – Unique identifier for this database. Used in MCP tools to reference specific databases. Must be unique across all databases in the configuration.

• description – Human-readable description of the database purpose or contents. Useful for documentation and understanding the database role.

• db_type – Database type identifier (e.g., ‘sqlite’, ‘postgres’, ‘mysql’, ‘aws_redshift’). Must match a valid DbTypeEnum value.

• connection – Database connection configuration. The specific type depends on the database type ( SqlalchemyConnection, AWSRedshiftConnection, etc.).

• schemas – List of Schema configurations for this database. Each schema can have its own table filtering rules.

Examples:

SQLite database:

{
    "identifier": "app_db",
    "description": "Main application database",
    "db_type": "sqlite",
    "connection": {
        ...
    },
    "schemas": [
        {
            "name": null,
            "table_filter": {
                "exclude": ["migrations", "temp_*"]
            }
        }
    ]
}

Note

The connection field uses Pydantic’s discriminator feature to automatically select the appropriate connection type based on the “type” field in the connection configuration.

classmethod check_name(value: str) → str

Validate the db_type field.

property db_type_enum: DbTypeEnum

Get the database type as an DbTypeEnum.

property schemas_mapping: dict[str, Schema]

Create a mapping of schema names to Schema objects.

property sa_metadata: MetaData

Create SQLAlchemy metadata for this database.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mcp_ohmy_sql.config.define.Config(*, version: str, settings: ~mcp_ohmy_sql.config.define.Settings = <factory>, databases: list[~mcp_ohmy_sql.config.define.Database])

Root configuration object for the mcp_ohmy_sql MCP server.

This is the main configuration class that contains all settings, database connections, and server configuration. It provides methods for loading and validating configuration from JSON files.

Parameters:

• version – Configuration schema version. Currently must be “0.1.1”. Used for backward compatibility and migration handling.

• settings – Global server Settings. For features like query timeouts, result limits, etc.

• databases – List of Database configurations. Each database must have a unique identifier and can contain multiple schemas.

Configuration File Structure:

The JSON configuration file should follow this structure:

{
    "version": "0.1.1",
    "settings": {...},
    "databases": [
        {
            "identifier": "my first database",
            ...
        }
        {
            "identifier": "my second database",
            ...
        }
    ]
}

Usage:

Load from environment variable:

import os
from pathlib import Path

config_path = Path(os.environ["MCP_OHMY_SQL_CONFIG"])
config = Config.load(config_path)

Access databases:

# Get all databases
for db in config.databases:
    print(f"Database: {db.identifier}")

# Get specific database
db = config.databases_mapping["my_db"]

# Get database schemas
for schema in db.schemas:
    print(f"Schema: {schema.name}")

Validation:

The configuration is validated when loaded using Pydantic. Common validation errors include:

• Missing required fields (version, databases)

• Invalid version number

• Duplicate database identifiers

• Invalid database types

• Invalid connection configurations

Environment Loading:

The typical usage pattern is to load configuration from an environment variable that points to the JSON configuration file:

export MCP_OHMY_SQL_CONFIG=/path/to/config.json

This allows different configurations for different environments (development, staging, production) without code changes.

Troubleshooting:

Common configuration issues:

1. File not found: Check MCP_OHMY_SQL_CONFIG environment variable

2. JSON syntax errors: Validate JSON with a JSON linter

3. Validation errors: Check field names and types match the schema

4. Connection errors: Verify database URLs and credentials

5. Permission errors: Ensure file is readable by the process

classmethod load(path: Path) → Config

Load configuration from a JSON file.

Reads and parses a JSON configuration file, validates it against the configuration schema, and returns a Config object. Provides detailed error messages for common configuration problems.

Paaram path:

Path to the JSON configuration file. Must be readable by the current process.

Returns:

Config Validated configuration object ready for use.

Raises:

If file cannot be read, JSON is invalid, or validation fails. Error messages include specific details about the failure to help with troubleshooting.

This method performs three validation steps:

1. File system access (can read the file)

2. JSON parsing (valid JSON syntax)

3. Schema validation (matches expected structure and types)

property databases_mapping: dict[str, Database]

Create a mapping of database identifiers to Database objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].