Database Intelligence Layer

TernoDBI：データベースインテリジェンスレイヤー

TernoDBI は、セキュリティと正確性を重視して構築された、AI エージェント向けのデータレイヤーです。エージェントがデータベース（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 クライアントを接続する — MCP サーバーとしての TernoDBIを参照してください。
6. データとのチャットを始める。

主な機能

• データベース： 1 つの API から Postgres、MySQL、Snowflake、BigQuery、Databricks、Oracle、SQLite を利用できます。
• 業務ツール（API コネクター）： 広告、分析、CRM、コマース、ドキュメントの 17 のソースに、同じエージェントツールを通じてクエリを実行できます。API コネクターを参照してください。
• デフォルトで安全：
  • SQLShield： 実行前にすべてのクエリを解析して書き換えます。受け付けるのは SELECT のみです。書き込みや複文がデータベースに届くことはありません。
  • 行レベルセキュリティ： ロールごとに、SQL フィルター（例：department_id = 5）をすべてのクエリに挿入します。
  • 非公開テーブルとカラム： ロールに閲覧権限がない場合、モデルのコンテキストから隠されます。
  • スコープ付きトークン： 組織別、データソース別に有効期限を設定できます。書き込みを伴う操作には、OAuth スコープと組織管理者によるチェックが適用されます。
• LLM 対応スキーマ：
  • セマンティック名： t_users_v2_fnl の代わりに Customers を公開します。テーブルとカラムには説明を設定できます。
  • カラム統計： モデルが正しいフィルターを記述できるよう、行数と NULL 数、カーディナリティ、一般的な値を提供します。
• メモリと組織プロンプト： エージェントが回答前に読み込む、組織別およびユーザー別の永続的な情報と指示です。
• MCP の 2 つの方式：
  • stdio： それぞれ独自のトークンを使用する、個別のクエリ（読み取り専用）サーバーと管理サーバー。
  • ホスト型 HTTP： OAuth 2.1（動的クライアント登録、PKCE、同意画面）を備えた単一サーバーに加え、未リリースのツール用の preview チャネルを提供します。
• 大きな結果： サーバー側カーソルにより、行を NDJSON としてストリーミングするか、CSV としてダウンロードできます。

使用方法とコア API

サーバーの実行

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

ternodbi start は REST API と管理パネルを実行します。MCP も HTTP（/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 で設定できます。

MCP サーバーとしての TernoDBI

クエリツール（読み取り専用）

ツール	機能
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 を使用する 1 つのサーバーとして提供されます。ユーザーは OAuth 2.1（動的クライアント登録、PKCE、組織を選択する同意画面を含む）でサインインするため、API キーをクライアントに貼り付ける必要はありません。書き込みアクセスには、書き込みスコープと組織管理者ロールの両方が必要で、リクエストごとに再確認されます。

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

このサーバーは 2 つのリリースチャンネルを提供します。/mcp（安定版：リリース済みのツールを提供し、意図的な場合にのみ変更）と /mcp/preview（安定版で未リリースのツールを含むすべてのツールを提供）です。OAuth のディスカバリー、スコープ、ツールのリリースについては、MCP ガイドを参照してください。

API コネクター

データベースに加えて、TernoDBI はビジネスツールにも接続し、同じエージェントのワークフローを通じてクエリを実行します。

カテゴリー	ソース
広告	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

各プロバイダーで、リダイレクト URI として <your server>/connectors/oauth/callback/ を登録してください。

クエリの実行。 エージェントは list_accounts（管理者が許可したアカウントのみ）、list_fields（ディメンションとメトリクス）、data_query（query_id を返します）、get_query_results を使用します。リクエストは組織およびソースごとにレート制限されます。

書き込み操作。 一部のソースでは、キャンペーンの一時停止などの変更が可能です（list_actions、execute_action）。書き込みには、connector:write スコープ、組織管理者ロール、および該当アカウントでの書き込みの有効化（デフォルトではオフ）のすべてが必要です。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 エージェント（LangChain、AutoGen、OpenAI Agents SDK）

任意のエージェントは、MCP ホストなしで REST API を使用できます。

1. エージェント用の 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 をお読みください。

セキュリティ

脆弱性を公開の Issue で報告しないでください。非公開での報告方法については、SECURITY.md を参照してください。

コミュニティとサポート

• バグ報告や機能リクエストには Issues をご利用ください。
• 質問やアイデアの共有には Discussions をご利用ください。

ライセンス

TernoDBI は Apache 2.0 License のもとで公開されているオープンソースです。LICENSE を参照してください。