Databricks Volume

Set up the Databricks Unity Catalog volume resource in Python.

Dependencies

uv add 'mirage-ai[databricks]'

For credential setup, see the Databricks Volume Setup guide.

Configuration

Static token

import os

from mirage import Workspace, MountMode
from mirage.resource.databricks_volume import (
    DatabricksVolumeConfig,
    DatabricksVolumeResource,
    StaticTokenProvider,
)

config = DatabricksVolumeConfig(
    host=os.environ["DATABRICKS_HOST"],
    catalog="main",
    schema="default",
    volume="agent_files",
    root_path="/reports",
)
resource = DatabricksVolumeResource(
    config,
    token_provider=StaticTokenProvider(os.environ["DATABRICKS_TOKEN"]),
)
ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)

Profile-based auth

import os

from mirage.resource.databricks_volume import DatabricksProfileTokenProvider

host = os.environ["DATABRICKS_HOST"]
config = DatabricksVolumeConfig(
    host=host,
    catalog="main",
    schema="default",
    volume="agent_files",
)
resource = DatabricksVolumeResource(
    config,
    token_provider=DatabricksProfileTokenProvider(host, profile="DEV"),
)
ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)

Custom token strategy

Implement get_token() when the application owns token caching, refresh, or request-scoped OBO credentials. It may return a string or an awaitable string.

class AppTokenProvider:
    async def get_token(self) -> str:
        return await application_credentials.current_token()


config = DatabricksVolumeConfig(
    host="https://example.cloud.databricks.com",
    catalog="main",
    schema="default",
    volume="agent_files",
)
resource = DatabricksVolumeResource(
    config,
    token_provider=AppTokenProvider(),
)
ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)

Mirage asks the provider for a token at each Files API operation. The provider decides whether to return a cached token or refresh it. Mirage does not retry a rejected token.

Config Reference

Field	Required	Default	Description
catalog	Yes		Unity Catalog catalog name.
schema	Yes		Unity Catalog schema name.
volume	Yes		Unity Catalog volume name.
host	Yes		Databricks workspace host.
root_path	No	/	Subdirectory inside the volume to expose.
timeout	No	30	Request timeout in seconds.

Notes

• Supports both read and write mount modes (MountMode.READ / MountMode.WRITE).
• Credentials are supplied separately through a token provider and are never serialized.
• root_path is normalized and cannot contain ...