fabric-dw

fabric-dw

用于 Microsoft Fabric Data Warehouses 和 SQL Analytics Endpoints 的 Python 命令行工具和 MCP 服务：可从终端或 AI Agent 对其进行管理、查询、优化和保护。

完整文档：fdw.debruyn.dev

📣 刚刚发布！ 阅读 公告博客文章，了解 fabric-dw 背后的故事。

描述

fabric-dw 提供两种接口，用于管理 Microsoft Fabric Data Warehouses 和 SQL Analytics Endpoints：

• 命令行工具：用于常见 DW 管理任务的命令行工具。
• MCP 服务：一种 Model Context Protocol 服务，可将 DW 操作作为工具提供给 AI 助手。

身份验证通过 FABRIC_AUTH 环境变量配置。默认设置（FABRIC_AUTH=default）使用 azure-identity DefaultAzureCredential，依次检查环境变量、工作负载/托管标识、Azure CLI、Azure Developer CLI、Azure PowerShell 和交互式浏览器。上述任一方式均可满足身份验证要求。有关完整身份验证链、所有支持的来源和调试提示，请参阅身份验证文档。

安装

pip install fabric-dw
# or run without installing:
uvx fabric-dw --help
# or install persistently on PATH:
uv tool install fabric-dw

安装后，fdw 命令是 fabric-dw 的简写别名；两者调用相同的入口点。有关 MCP 服务设置、升级和预发布版本，请参阅安装文档。

快速开始

命令行工具

工作区是一个全局根选项 -w / --workspace，应放在命令组之前。使用 fdw config set workspace <NAME> 一次性设置默认工作区，之后每次调用都可省略 -w。工作区解析顺序为：(1) -w 标志，(2) FABRIC_DW_DEFAULT_WORKSPACE 环境变量，(3) 已配置的默认值。

# Run without installing; install to get the fdw alias
uvx fabric-dw --help

# Set a default workspace once; all subsequent commands pick it up
fdw config set workspace SalesWS

# -- Run and explain SQL --

# Execute a query against a warehouse
fdw sql exec SalesWH -q "SELECT TOP 10 * FROM dbo.orders ORDER BY order_date DESC"

# Capture an estimated execution plan as SVG -- no SSMS or Windows needed
fdw sql plan SalesWH -f query.sql --format svg -o plan.svg

# -- Performance mission-control --

# See what is running right now
fdw queries running SalesWH

# Long-running queries from the past hour
fdw queries long-running SalesWH --ago 1h

# Kill a runaway session by ID
fdw queries kill SalesWH 55

# Most-repeated queries over the past 24 hours
fdw queries frequent SalesWH --ago 24h

# -- Optimize --

# Inspect a statistics histogram with inline terminal bar charts
fdw statistics show SalesWH dbo.orders st_order_date --histogram

# Re-cluster a table on a new key (transactional CTAS-swap, auto-rollback on failure)
fdw tables cluster-by SalesWH dbo.orders --cluster-by customer_id

# -- Time travel + export --

# Browse the table as it looked 2 hours ago
fdw tables read SalesWH dbo.orders --ago 2h

# Export a point-in-time snapshot to Parquet
fdw tables export SalesWH dbo.orders --output snapshot.parquet --ago 2h

# -- Governance --

# Grant SELECT on a specific table
fdw permissions sql grant SalesWH SELECT --to [email protected] --object dbo.orders

# Deny access to sensitive columns (column-level security)
fdw permissions cls deny SalesWH SELECT --to [email protected] \
    --object dbo.orders --columns salary,bonus

# Create a row-level security policy (filter rows by SalesRep)
fdw permissions rls create SalesWH rls.SalesFilter \
    --filter "rls.fn_sales_filter(SalesRep)" --on dbo.orders

# -- Load + scaffold --

# Load a local Parquet file and auto-create the table from its schema
fdw tables load SalesWH dbo.orders --file orders.parquet --create

# Scaffold a full dbt-fabric project wired to the warehouse
fdw dbt init SalesWH ./my-dbt-project --project-name sales_dw --with-sources

MCP 服务

将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop、VS Code）：

{
  "mcpServers": {
    "fabric-dw": {
      "command": "uvx",
      "args": ["--from", "fabric-dw", "fabric-dw-mcp"]
    }
  }
}

MCP 服务会将所有命令行操作作为 MCP 工具公开（workspaces、warehouses、SQL endpoints、schemas、tables、views、queries、snapshots、restore points、audit、statistics、permissions、sql-pools）。其中还包含打包的 Claude Code Agent 技能（query-optimizer、warehouse-performance、dbt-setup），用于更深入的 AI 辅助分析。如果需要使用非默认身份验证模式，请在环境中设置 FABRIC_AUTH。

Claude Code 和 GitHub Copilot CLI 均可通过 fabric-dw 插件市场使用一条命令安装这些技能和 MCP 服务：/plugin marketplace add sdebruyn/fabric-dw-mcp-cli，然后运行 /plugin install fabric-dw@fabric-dw。详情请参阅 Agent 技能文档。

在 Docker 中运行

Docker 镜像的默认 ENTRYPOINT 是 MCP 服务（fabric-dw-mcp）。可直接将其与 MCP 客户端搭配使用，也可以覆盖入口点以改为运行 CLI。

docker pull ghcr.io/sdebruyn/fabric-dw:latest

# Run the MCP server (default entrypoint, connect via stdio from your MCP client):
docker run --rm -i \
  -e AZURE_CLIENT_ID=… \
  -e AZURE_TENANT_ID=… \
  -e AZURE_CLIENT_SECRET=… \
  -e FABRIC_AUTH=sp \
  ghcr.io/sdebruyn/fabric-dw

# Run the CLI instead (override the entrypoint):
docker run --rm \
  --entrypoint fabric-dw \
  -e AZURE_CLIENT_ID=… \
  -e AZURE_TENANT_ID=… \
  -e AZURE_CLIENT_SECRET=… \
  -e FABRIC_AUTH=sp \
  ghcr.io/sdebruyn/fabric-dw --help

开发版镜像（每次合并到 main 后构建）：ghcr.io/sdebruyn/fabric-dw:main 或 :<version>.dev<N>。

软件包页面：ghcr.io/sdebruyn/fabric-dw

安全环境变量

变量	默认值	描述
FABRIC_MCP_READONLY	未设置	设置为 1，将 execute_sql 限制为 SELECT/WITH，并阻止所有会修改数据的工具。
FABRIC_MCP_ALLOW_DESTRUCTIVE	未设置	设置为 1，启用具有永久破坏性的工具（delete_*、clear_table、restore_warehouse_in_place）。默认禁用。
FABRIC_MCP_WORKSPACES	未设置	以逗号分隔的工作区名称或 GUID，限定服务可访问的工作区。未设置 = 允许访问所有工作区。
FABRIC_MCP_ALLOW_REMOTE	未设置	设置为 1，允许 HTTP 传输（--transport http）绑定到非 loopback 地址。系统会记录警告；请确保端点前方设有带 TLS 的身份验证反向代理，并传入 --allowed-host，以保持 Host 验证启用。请参阅托管 MCP 服务。

HTTP 传输

MCP 服务可通过 HTTP 模式启动，以供远程客户端使用：

fabric-dw-mcp --transport http [--host 127.0.0.1] [--port 8000]

默认情况下，它会绑定到 loopback 地址，并为你处理 Host 和 Origin 验证。绑定到其他地址则需要设置 FABRIC_MCP_ALLOW_REMOTE=1 并传入 --allowed-host。端点没有内置身份验证或 TLS，因此务必在其前方设置带身份验证的反向代理。有关该配置，请参阅托管 MCP 服务。

在容器中开发

在 GitHub Codespaces 或 VS Code 的 Remote-Containers 扩展中打开仓库。devcontainer 会预先安装 Python 3.14、uv、Azure CLI 和 GitHub CLI。

参与贡献

有关开发环境设置、分支流程以及如何在本地运行测试，请参阅 CONTRIBUTING.md。

📖 文档：fdw.debruyn.dev（或在本地运行 uv run --only-group docs zensical serve）。

安全

请私下报告漏洞。请参阅 SECURITY.md。

行为准则

本项目遵循 Contributor Covenant 2.1。

许可证

MIT。版权所有 (c) 2026 Sam Debruyn