Databricks connectors and sandboxes

Databricks appears in both the sandbox and connector layers, but those layers solve different problems. Select them by capability rather than by provider name.

SQL sandbox

databricksSqlSandbox() adapts session.shell(sql) to SQL Statement Execution on a SQL Warehouse. It returns JSONL or CSV in stdout. Its small filesystem is in-memory session storage; it is not DBFS, a Volume, a cluster driver, or an operating-system shell.

import { databricksSqlSandbox } from '@fabric-harness/databricks/sql-sandbox';
import { init } from '@fabric-harness/sdk';

const runtime = await init({
  sandbox: databricksSqlSandbox({
    host: process.env.DATABRICKS_HOST!,
    token: async () => workspaceIdentity(),
    warehouseId: process.env.DATABRICKS_WAREHOUSE_ID!,
    catalog: 'main',
    schema: 'analytics',
    resultFormat: 'jsonl',
  }),
});

const session = await runtime.session();
const result = await session.shell(`
  SELECT region, sum(net_revenue) AS revenue
  FROM orders
  GROUP BY region
  ORDER BY revenue DESC
`);

Use databricksSqlTool() instead when the model should call a named SQL tool alongside other tools. The sandbox is useful when the session's shell abstraction should itself mean SQL.

Unity Catalog Volume connector

The connector uses the Databricks Files API and keeps all paths under a configured /Volumes/<catalog>/<schema>/<volume> root.

import { databricksVolumeSource } from '@fabric-harness/connectors/databricks-volume';

const source = databricksVolumeSource({
  host: process.env.DATABRICKS_HOST!,
  token: async () => workspaceIdentity(),
  volumePath: '/Volumes/main/support/knowledge',
  include: (path) => path.endsWith('.md') || path.endsWith('.pdf'),
});

await session.mount('/knowledge', source);

databricksVolumeWriter() provides scoped put() and delete() operations. Use UcVolumesAttachmentStore when attachments must participate in Fabric's attachment lifecycle. The acting principal still needs the relevant USE CATALOG, USE SCHEMA, and Volume privileges.

General-purpose code execution

For Python, package installation, bash, repository mutation, or untrusted code, use a code sandbox such as Docker, Kubernetes, E2B, Daytona, Modal, or another remote backend. Give that sandbox Databricks tools or scoped OAuth access as needed. This preserves the common sandbox interface without pretending a SQL Warehouse is a machine shell.

See the focused Databricks SQL sandbox reference and the sandbox matrix.