Configuration

Metaxy can be configured using TOML configuration files or environment variables.

Default Configuration

Here is the complete default configuration with all available options:

!metaxy.tomlpyproject.toml

# Default metadata store to use
store = "dev"

# Optional: Named store configurations
# stores = {}

# Directory where migration files are stored
migrations_dir = ".metaxy/migrations"

# Optional: List of Python module paths to load for feature discovery
# entrypoints = []

# Graph rendering theme for CLI visualization
theme = "default"

# Optional: Truncate hash values to this length (minimum 8 characters). None = no truncation.
# hash_truncation_length = null

# Auto-create tables when opening stores (development/testing only). WARNING: Do not use in production. Use proper database migration tools like Alembic.
auto_create_tables = false

# Project name for metadata isolation. Used to scope system tables and operations to enable multiple independent projects in a shared metadata store. Does not modify feature keys or table names. Project names must be valid identifiers (alphanumeric, underscores, hyphens) and cannot contain forward slashes (/) or double underscores (__)
project = "default"

[ext.sqlmodel]
# Whether to enable the plugin.
enable = false

# Whether to automatically use `FeatureKey.table_name` for sqlalchemy's __tablename__ value.
infer_db_table_names = true

# Whether to use SQLModel definitions for system tables (for Alembic migrations).
system_tables = true

[tool.metaxy]
# Default metadata store to use
store = "dev"

# Optional: Named store configurations
# stores = {}

# Directory where migration files are stored
migrations_dir = ".metaxy/migrations"

# Optional: List of Python module paths to load for feature discovery
# entrypoints = []

# Graph rendering theme for CLI visualization
theme = "default"

# Optional: Truncate hash values to this length (minimum 8 characters). None = no truncation.
# hash_truncation_length = null

# Auto-create tables when opening stores (development/testing only). WARNING: Do not use in production. Use proper database migration tools like Alembic.
auto_create_tables = false

# Project name for metadata isolation. Used to scope system tables and operations to enable multiple independent projects in a shared metadata store. Does not modify feature keys or table names. Project names must be valid identifiers (alphanumeric, underscores, hyphens) and cannot contain forward slashes (/) or double underscores (__)
project = "default"

[tool.metaxy.ext.sqlmodel]
# Whether to enable the plugin.
enable = false

# Whether to automatically use `FeatureKey.table_name` for sqlalchemy's __tablename__ value.
infer_db_table_names = true

# Whether to use SQLModel definitions for system tables (for Alembic migrations).
system_tables = true

Configuration Fields

Each field can be set via TOML configuration or environment variables.

store

Default metadata store to use

Type: str | Default: "dev"

!metaxy.tomlpyproject.toml

store = "dev"

[tool.metaxy]
store = "dev"

Environment Variable:

export METAXY_STORE=dev

---

stores

Named store configurations

Type: dict[str, metaxy.config.StoreConfig]

!metaxy.tomlpyproject.toml

# Optional
# stores = {}

[tool.metaxy]
# Optional
# stores = {}

Environment Variable:

export METAXY_STORES=...

---

migrations_dir

Directory where migration files are stored

Type: str | Default: ".metaxy/migrations"

!metaxy.tomlpyproject.toml

migrations_dir = ".metaxy/migrations"

[tool.metaxy]
migrations_dir = ".metaxy/migrations"

Environment Variable:

export METAXY_MIGRATIONS_DIR=.metaxy/migrations

---

entrypoints

List of Python module paths to load for feature discovery

Type: list[str]

!metaxy.tomlpyproject.toml

# Optional
# entrypoints = []

[tool.metaxy]
# Optional
# entrypoints = []

Environment Variable:

export METAXY_ENTRYPOINTS=...

---

theme

Graph rendering theme for CLI visualization

Type: str | Default: "default"

!metaxy.tomlpyproject.toml

theme = "default"

[tool.metaxy]
theme = "default"

Environment Variable:

export METAXY_THEME=default

---

hash_truncation_length

Truncate hash values to this length (minimum 8 characters). None = no truncation.

Type: int | None

!metaxy.tomlpyproject.toml

# Optional
# hash_truncation_length = null

[tool.metaxy]
# Optional
# hash_truncation_length = null

Environment Variable:

export METAXY_HASH_TRUNCATION_LENGTH=...

---

auto_create_tables

Auto-create tables when opening stores (development/testing only). WARNING: Do not use in production. Use proper database migration tools like Alembic.

Type: bool | Default: False

!metaxy.tomlpyproject.toml

auto_create_tables = false

[tool.metaxy]
auto_create_tables = false

Environment Variable:

export METAXY_AUTO_CREATE_TABLES=false

---

project

Project name for metadata isolation. Used to scope system tables and operations to enable multiple independent projects in a shared metadata store. Does not modify feature keys or table names. Project names must be valid identifiers (alphanumeric, underscores, hyphens) and cannot contain forward slashes (/) or double underscores (__)

Type: str | Default: "default"

!metaxy.tomlpyproject.toml

project = "default"

[tool.metaxy]
project = "default"

Environment Variable:

export METAXY_PROJECT=default

---

Ext > Sqlmodel Configuration

ext.sqlmodel.enable

Whether to enable the plugin.

Type: bool | Default: False

!metaxy.tomlpyproject.toml

[ext.sqlmodel]
enable = false

[tool.metaxy.ext.sqlmodel]
enable = false

Environment Variable:

export METAXY_EXT__SQLMODEL__ENABLE=false

---

ext.sqlmodel.infer_db_table_names

Whether to automatically use FeatureKey.table_name for sqlalchemy's tablename value.

Type: bool | Default: True

!metaxy.tomlpyproject.toml

[ext.sqlmodel]
infer_db_table_names = true

[tool.metaxy.ext.sqlmodel]
infer_db_table_names = true

Environment Variable:

export METAXY_EXT__SQLMODEL__INFER_DB_TABLE_NAMES=true

---

ext.sqlmodel.system_tables

Whether to use SQLModel definitions for system tables (for Alembic migrations).

Type: bool | Default: True

!metaxy.tomlpyproject.toml

[ext.sqlmodel]
system_tables = true

[tool.metaxy.ext.sqlmodel]
system_tables = true

Environment Variable:

export METAXY_EXT__SQLMODEL__SYSTEM_TABLES=true

---

Configuration Types

StoreConfig

Configuration for a single metadata store backend.

Fields:

• type (str): Full import path to the store class
• config (dict[str, Any]): Store-specific configuration options

ExtConfig

Configuration for Metaxy integrations with third-party tools.

Fields:

• sqlmodel (SQLModelConfig): SQLModel integration configuration

SQLModelConfig

Configuration for SQLModel integration.

Fields:

• enable (bool): Whether to enable the plugin (default: false)
• infer_db_table_names (bool): Whether to automatically use FeatureKey.table_name for sqlalchemy's __tablename__ value (default: true)
• system_tables (bool): Whether to use SQLModel definitions for system tables (default: true)

Store Configuration

The stores field configures metadata store backends. Each store is defined by:

• type: Full import path to the store class (e.g., metaxy.metadata_store.duckdb.DuckDBMetadataStore)
• config: Dictionary of store-specific configuration options

Example: Multiple Stores with Fallback Chain

!metaxy.tomlpyproject.toml

# Default store to use
store = "dev"

# Development store (in-memory) with fallback to production
[stores.dev]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[stores.dev.config]
db_path = ":memory:"
fallback_stores = ["prod"]

# Production store
[stores.prod]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[stores.prod.config]
db_path = "s3://my-bucket/metadata.duckdb"

[tool.metaxy]
store = "dev"

[tool.metaxy.stores.dev]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[tool.metaxy.stores.dev.config]
db_path = ":memory:"
fallback_stores = ["prod"]

[tool.metaxy.stores.prod]
type = "metaxy.metadata_store.duckdb.DuckDBMetadataStore"
[tool.metaxy.stores.prod.config]
db_path = "s3://my-bucket/metadata.duckdb"

Available Store Types

Store Type	Import Path	Description
DuckDB	metaxy.metadata_store.duckdb.DuckDBMetadataStore	File-based or in-memory DuckDB backend
ClickHouse	metaxy.metadata_store.clickhouse.ClickHouseMetadataStore	ClickHouse database backend
In-Memory	metaxy.metadata_store.memory.InMemoryMetadataStore	In-memory backend for testing

Getting a Store Instance

from metaxy.config import MetaxyConfig

config = MetaxyConfig.load()

# Get the default store
with config.get_store() as store:
    # Use store
    pass

# Get a specific store by name
with config.get_store("prod") as store:
    # Use store
    pass

Configuration Priority

When the same setting is defined in multiple places, Metaxy uses the following priority order (highest to lowest):

1. Explicit arguments - Values passed directly to MetaxyConfig()
2. Environment variables - Values from METAXY_* environment variables
3. Configuration files - Values from metaxy.toml or pyproject.toml

This allows you to override file-based configuration with environment variables, which is useful for CI/CD pipelines and different deployment environments.

Loading Configuration

Auto-Discovery

from metaxy.config import MetaxyConfig

# Auto-discover config file in current or parent directories
config = MetaxyConfig.load()

Explicit File

# Load from specific file
config = MetaxyConfig.load("path/to/metaxy.toml")

Programmatic Configuration

# Create configuration programmatically
config = MetaxyConfig(
    store="prod",
    migrations_dir=".migrations",
)