Database Intelligence Layer

TernoDBI：数据库智能层

TernoDBI 是一个面向 AI Agent 的数据层，专为安全性和准确性打造。它为 Agent 提供统一且受控的方式来读取你的数据库（Postgres、MySQL、Snowflake、BigQuery、Databricks、Oracle、SQLite）和业务工具（Google Ads、GA4、HubSpot、Salesforce、Shopify 等），并在每次查询时强制执行访问规则。

可将其作为独立的 Model Context Protocol（MCP） 服务运行——通过 stdio 在本地运行，或通过带 OAuth 的 HTTP 托管运行；也可将其嵌入现有的 Django 项目中。

快速开始：5 分钟内与数据库对话

1. 安装 TernoDBI

   pip install terno-dbi
   

2. 启动服务

   ternodbi start [port]
   

   默认情况下，服务会在 127.0.0.1:8376 启动。首次启动时，它会运行迁移、创建 admin / admin 用户和 default 组织。服务以开发模式运行，在你自己的机器上使用没有问题——在将其公开到任何网络之前，请参阅配置。
3. 添加数据库 打开 http://127.0.0.1:8376/admin 管理面板并添加数据源。凭据会在静态存储时加密。
4. 生成访问令牌，并将其绑定到组织和用户（--org / --user）——未绑定的令牌无法使用记忆等组织功能：

   # Query token (read-only, for AI agents)
   ternodbi manage issue_token --name "My Agent" --type query --org default --user admin
   
   # Admin token (schema metadata, memory, organisation prompt)
   ternodbi manage issue_token --name "System Admin" --type admin --org default --user admin
   

5. 连接你的 MCP 客户端——请参阅 将 TernoDBI 用作 MCP 服务。
6. 开始与你的数据对话。

主要功能

• **数据库：**通过一个 API 支持 Postgres、MySQL、Snowflake、BigQuery、Databricks、Oracle 和 SQLite。
• **业务工具（API 连接器）：**17 种数据源，涵盖广告、分析、CRM、电商和文档，可通过相同的 Agent 工具进行查询。请参阅 API 连接器。
• 默认安全：
  • **SQLShield：**每条查询在执行前都会经过解析和重写。只接受 SELECT；写入操作和堆叠语句绝不会到达你的数据库。
  • **行级安全：**按角色将 SQL 筛选条件（例如 department_id = 5）注入每条查询。
  • **私有表和列：**除非角色获准查看，否则不会显示在模型上下文中。
  • **范围限定的令牌：**按组织、按数据源进行限定，并可设置有效期；OAuth 作用域以及针对任何写入操作的组织管理员检查。
• 面向大模型的架构：
  • **语义名称：**使用 Customers 而非 t_users_v2_fnl；提供表和列的描述。
  • **列统计信息：**行数和空值计数、基数及常见值，帮助模型编写正确的筛选条件。
• **记忆和组织提示词：**持久化事实和指令，Agent 在回答前会按组织和用户读取这些内容。
• 两种 MCP 方式：
  • **stdio：**分别提供 查询（只读）和 管理 服务，每个服务都有自己的令牌。
  • **托管 HTTP：**通过 OAuth 2.1 提供单一服务（动态客户端注册、PKCE、同意界面），并提供用于尚未发布工具的 preview 通道。
• **大型结果集：**服务端游标可将行数据流式传输为 NDJSON，或下载为 CSV。

用法与核心 API

运行服务

ternodbi start          # default port 8376
ternodbi start 9000     # custom port

ternodbi start 会运行 REST API 和管理面板。要同时通过 HTTP 提供 MCP（/mcp），请运行 ASGI 应用——请参阅通过 HTTP 托管。

与现有 Django 项目共享数据库

如果你的 Django 项目嵌入了 terno_dbi.core 并使用 SQLite，独立服务可以读写同一个数据库文件：

DJANGO_PROJECT_PATH=/path/to/your/django/project ternodbi start

这会使用 /path/to/your/django/project/db.sqlite3。

管理命令

始终传入 --org / --user，以便为令牌指定身份：

# Query token that expires in 30 days
ternodbi manage issue_token --name "Claude Agent" --type query --expires 30 --org acme --user alice

# Admin token
ternodbi manage issue_token --name "System Admin" --type admin --org acme --user alice

# Token restricted to one datasource
ternodbi manage issue_token --name "Finance Data Only" --type query --datasource 1 --org acme --user alice

ternodbi manage 可运行任何 Django 管理命令（migrate、createsuperuser 等）。

查询 API

每个请求都携带 Authorization: Bearer <token>。数据源可通过 ID 或显示名称指定。

端点	用途
GET /api/query/datasources/	此令牌可访问的数据源
GET /api/query/datasources/{ds}/tables/	按公开名称列出表
GET /api/query/datasources/{ds}/tables/{table}/columns/	列和类型
GET /api/query/tables/{table_id}/sample/?rows=10	示例行（最多 100 行）
POST /api/query/datasources/{ds}/query/	执行查询，结果为 JSON
POST /api/query/datasources/{ds}/stream/	执行查询，结果以 NDJSON 流式传输
POST /api/query/datasources/{ds}/export/	执行查询，结果以 CSV 文件下载

POST /api/query/datasources/1/query/
{
    "sql": "SELECT name, email FROM Customers WHERE country = 'DE'",
    "max_rows": 500
}

查询使用公开（语义）名称，并由 SQLShield 根据调用者的角色进行重写。结果行数上限为 MAX_QUERY_ROWS（默认为 10,000），超时时间为 300 秒；两者都可在 DBI_LAYER 中配置。

将 TernoDBI 用作 MCP 服务

查询工具（只读）

工具	功能
list_datasources	此连接可访问的数据源
list_tables、list_table_columns	按公开名称列出架构
get_sample_data	获取表中的示例行
execute_query	通过 SQLShield 执行 SQL
list_memories、get_memory、grep_memory	读取已存储的记忆
get_org_prompt、grep_org_prompt	读取组织提示词
terno_guide	了解服务，或查看最新内容

管理工具

工具	功能
connect_datasource	返回一个链接，供用户添加数据源——凭据不会经过聊天
add_datasource、validate_connection	添加或测试连接字符串（仅限 stdio；OAuth 下绝不提供）
delete_datasource	移除数据库连接；如果是 API 连接器，则会断开连接并保留其设置
sync_metadata	从数据库刷新架构
rename_table、rename_column	设置公开名称
update_table_description、update_column_description、get_table_info	编写描述，并提供列统计信息供参考
save_memory、edit_memory、delete_memory	管理记忆
update_org_prompt、edit_org_prompt	管理组织提示词

该服务还提供提示词（explore-datasources、build-a-query、schema-health）和资源（ternodbi://docs、ternodbi://changelog）。API 连接器工具列于 API 连接器 中。

本地（stdio）：连接 Claude Desktop

1. 安装 Claude Desktop，然后打开 Settings → Developer → Edit Config。
2. 创建一个查询令牌和一个管理令牌（参见管理命令），并添加：

{
  "mcpServers": {
    "ternodbi-query": {
      "command": "uvx",
      "args": ["--from", "terno-dbi", "dbi-mcp", "query"],
      "env": {
        "TERNODBI_API_URL": "http://127.0.0.1:8376",
        "TERNODBI_API_KEY": "dbi_query_YOUR_TOKEN_HERE"
      }
    },
    "ternodbi-admin": {
      "command": "uvx",
      "args": ["--from", "terno-dbi", "dbi-mcp", "admin"],
      "env": {
        "TERNODBI_API_URL": "http://127.0.0.1:8376",
        "TERNODBI_API_KEY": "dbi_admin_YOUR_TOKEN_HERE"
      }
    }
  }
}

3. 重启 Claude Desktop 并询问：“显示可用的数据源。”

如果你在其他端口启动了 TernoDBI，请更新 TERNODBI_API_URL。

通过 OAuth 托管于 HTTP

托管模式下，两组工具都通过 Streamable HTTP 在同一服务上提供。用户通过 OAuth 2.1 登录——支持动态客户端注册、PKCE，以及供用户选择组织的授权页面——因此无需将 API 密钥粘贴到客户端中。写入访问权限既需要写入作用域，也需要 Org Admin 角色；每次请求都会重新检查。

pip install 'terno-dbi[http]'
uvicorn terno_dbi.server.asgi:application --port 8376

该服务提供两个发布渠道：/mcp（稳定版：已发布的工具，仅在有意发布变更时更新）和 /mcp/preview（包含所有工具，包括尚未在稳定版发布的工具）。有关 OAuth 发现、作用域和工具发布，请参阅 MCP 指南。

API 连接器

除了数据库之外，TernoDBI 还可连接业务工具，并通过相同的 Agent 工作流查询这些工具：

类别	数据源
广告	Google Ads、Meta Ads、LinkedIn Ads、Microsoft Ads、Amazon Ads、TikTok Ads、X Ads
分析	Google Analytics 4、Google Search Console、YouTube
社交	Instagram Insights、Instagram Public Data、X Analytics
CRM	HubSpot、Salesforce、Pipedrive、Zoho CRM
电商	Shopify
支付	Stripe
文档	Google Sheets、Google Drive

连接数据源。 组织管理员打开 /connect?connector=<key>（例如 google_ads），使用提供商账号登录，并选择允许 TernoDBI 查询哪些账号。令牌会加密存储并自动刷新。服务器需要为启用的每个提供商配置一个 OAuth 应用：

提供商	环境变量
Google（Ads、GA4、Search Console、YouTube、Sheets、Drive）	TERNO_GOOGLE_OAUTH_CLIENT_ID、TERNO_GOOGLE_OAUTH_CLIENT_SECRET
Meta（Meta Ads、通过 Facebook Login 登录 Instagram）	TERNO_META_APP_ID、TERNO_META_APP_SECRET
Instagram（Instagram Login）	TERNO_INSTAGRAM_APP_ID、TERNO_INSTAGRAM_APP_SECRET
LinkedIn	TERNO_LINKEDIN_CLIENT_ID、TERNO_LINKEDIN_CLIENT_SECRET
Microsoft Advertising	TERNO_MICROSOFT_ADS_CLIENT_ID、TERNO_MICROSOFT_ADS_CLIENT_SECRET
Amazon Ads	TERNO_AMAZON_ADS_CLIENT_ID、TERNO_AMAZON_ADS_CLIENT_SECRET
TikTok Ads	TERNO_TIKTOK_APP_ID、TERNO_TIKTOK_APP_SECRET
X Analytics（OAuth 2.0 客户端）	TERNO_X_CLIENT_ID、TERNO_X_CLIENT_SECRET
X Ads（OAuth 1.0a 消费者密钥）	TERNO_X_CONSUMER_KEY、TERNO_X_CONSUMER_SECRET
HubSpot	TERNO_HUBSPOT_CLIENT_ID、TERNO_HUBSPOT_CLIENT_SECRET
Salesforce	TERNO_SALESFORCE_CLIENT_ID、TERNO_SALESFORCE_CLIENT_SECRET
Pipedrive	TERNO_PIPEDRIVE_CLIENT_ID、TERNO_PIPEDRIVE_CLIENT_SECRET
Zoho	TERNO_ZOHO_CLIENT_ID、TERNO_ZOHO_CLIENT_SECRET
Shopify	TERNO_SHOPIFY_CLIENT_ID、TERNO_SHOPIFY_CLIENT_SECRET
Stripe（Connect 平台的 ca_… ID 和密钥）	TERNO_STRIPE_CLIENT_ID、TERNO_STRIPE_SECRET_KEY

在每个提供商处，将 <your server>/connectors/oauth/callback/ 注册为重定向 URI。

查询。 Agent 使用 list_accounts（仅限管理员允许的账号）、list_fields（维度和指标）、data_query（返回 query_id）和 get_query_results。请求会按组织和数据源进行速率限制。

写入操作。 部分数据源支持更改，例如暂停广告系列（list_actions、execute_action）。每次写入都必须同时满足以下条件：具有 connector:write 作用域、拥有 Org Admin 角色，并且已为对应账号启用写入操作（默认关闭）。dry_run 会向提供商验证操作，但不会实际应用；每次真实写入都会记录在审计日志中。

在托管服务器上，连接器工具目前位于 /mcp/preview 通道。

配置

独立服务会读取以下环境变量（完整列表请参阅设置指南）：

变量	用途	默认值
DBI_DEBUG	开发模式	True
DBI_SECRET_KEY	Django 签名密钥	不安全的占位符
DBI_ALLOWED_HOSTS	以逗号分隔的主机名	*
MCP_ENCRYPTION_KEY	用于加密已存储凭据和令牌的 Fernet 密钥（轮换时使用 MCP_ENCRYPTION_KEYS，以逗号分隔，最新密钥在前）	仅在开发环境中从 DBI_SECRET_KEY 派生
DATABASE_ENGINE	POSTGRESQL、MYSQL，或留空以使用 SQLite	SQLite
TERNO_MCP_BASE_URL	MCP 服务的公开 URL，用于 OAuth 发现	http://127.0.0.1:8376
TERNODBI_LOG_LEVEL	日志级别	INFO
TERNO_DISABLED_CONNECTORS	此部署暂停提供的连接器键，以逗号分隔——例如，在预发布环境中提供，但在生产环境中获批前隐藏。暂停提供的连接器不会在任何位置列出，也无法连接；现有连接仍可正常工作。	无

在自己的机器以外的任何环境中运行之前：

• 设置 DBI_DEBUG=False、随机生成的 DBI_SECRET_KEY 和 DBI_ALLOWED_HOSTS。
• 设置 MCP_ENCRYPTION_KEY——关闭开发模式后，没有它就无法存储凭据。使用 python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" 生成密钥，并妥善保管：丢失密钥会导致已存储的凭据无法读取。
• 更改首次启动时创建的 admin / admin 密码。
• 通过 HTTPS 提供服务。

高级集成

在 Django 项目中

1. pip install terno-dbi
2. 将 'terno_dbi.core' 添加到 INSTALLED_APPS。
3. 将 'terno_dbi.middleware.ServiceTokenMiddleware' 添加到 MIDDLEWARE，放在 AuthenticationMiddleware 之后——否则 API 令牌不会通过身份验证。
4. 在设置中配置 MCP_ENCRYPTION_KEY。
5. 包含 URL，例如 path('api/', include('terno_dbi.core.urls'))，并运行 python manage.py migrate。

随后即可在视图和任务中直接使用这些服务和模型。有关设置和自定义，请参阅 Django 集成指南。

自定义 AI Agent（LangChain、AutoGen、OpenAI Agents SDK）

任何 Agent 都可以不使用 MCP 主机，直接调用 REST API：

1. 为该 Agent 签发一个 query 令牌。
2. 列出数据源（/api/query/datasources/），然后查询所需数据源的表和列。
3. 将该架构放入提示词中，把生成的 SQL 发送到 /api/query/datasources/{ds}/query/，遇到 SQLShield 错误时重试。

可运行示例：src/terno_dbi/examples/agents/。运行 pip install 'terno-dbi[agents]' 会安装 LangChain、LangGraph、CrewAI 和 AutoGen；OpenAI Agents SDK 示例需要单独安装该 SDK。

文档

• 设置指南
• 系统架构
• MCP 集成
• 安全与 SQLShield
• Django 集成
• API 参考
• 更新日志

开发

git clone https://github.com/terno-ai/ternodbi.git
cd ternodbi
pip install -e '.[dev,http]'
pytest tests/unit
ruff check src tests

请参阅 CONTRIBUTING.md。

贡献

欢迎贡献，包括错误报告、连接器、文档和修复。请阅读 CONTRIBUTING.md，了解环境设置、测试以及我们对拉取请求的要求。

安全

请不要在公开议题中报告漏洞。关于如何私下报告，请参阅 SECURITY.md。

社区与支持

• 使用 Issues 报告错误和提交功能请求。
• 使用 Discussions 提问和交流想法。

许可证

TernoDBI 是基于 Apache 2.0 License 开源的。请参阅 LICENSE。