seekdb-cli

seekdb-cli — AI エージェント向けデータベース CLI

AI エージェント向けに設計されたコマンドラインクライアントです。すべての出力は JSON 構造で、ステートレスであり、安全性を確保するガードレールが組み込まれています。

前提条件

seekdb-cli がインストールされているか確認します（どちらのコマンドも同じエントリーポイントを共有しているため、どちらでも動作します）。

seekdb --version
# or, aligned with PyPI package name / for `which`-style checks:
seekdb-cli --version

インストールされていない場合は、環境に合った方法を選択してください。

推奨 — pipx（システムの Python 環境を汚さずに、グローバルに使用できます）：

# Install pipx first if needed (Ubuntu/Debian)
sudo apt install pipx && pipx ensurepath
# Then install seekdb-cli
pipx install seekdb-cli

代替 — pip（プロジェクトの仮想環境内、または PEP 668 に対応していないシステムの場合）：

pip install seekdb-cli

Ubuntu 23.04 以降／Debian 12 以降の場合： システムレベルでの直接の pip install は PEP 668 によってブロックされます。 代わりに pipx を使用してください。隔離された環境を作成しつつ、seekdb と seekdb-cli を PATH に追加します（同じプログラムです）。

このスキルでは、例に seekdb を使用しています。どこでも seekdb-cli に置き換えることができます。

埋め込み型とリモートの違い： デフォルトのローカルストアは埋め込み型モード（pyseekdb）を使用します。このモードには Linux（glibc ≥ 2.28）または macOS 15 以降が必要です。それ以外の OS では、リモート DSN に接続してください：seekdb --dsn "seekdb://user:pass@host:port/db" ...。

接続

DSN の解決順序（優先度の高い順）：

1. CLI の --dsn（サブコマンドより前に指定する必要があります）
2. SEEKDB_DSN 環境変数
3. 現在の作業ディレクトリの .env（SEEKDB_DSN=... の行）
4. ~/.seekdb/config.env
5. デフォルトの embedded:~/.seekdb/seekdb.db

設定がない場合は、デフォルトの埋め込みパスが適用されるため、コマンドをそのまま実行できます。ユーザーが特定の DSN を指定した場合は、--dsn を付けて渡してください：

# Remote mode
seekdb --dsn "seekdb://user:pass@host:port/db" schema tables

# Remote with TLS (query string on the URL; encode special characters in user/password)
# tls=skip-verify — encrypted, no certificate verification (common for self-signed servers)
seekdb --dsn "seekdb://user:pass@host:2881/db?tls=skip-verify" status
# tls=required — encrypted with default OS CA verification
seekdb --dsn "seekdb://user:pass@host:2881/db?tls=required" sql "SELECT 1"

# Embedded mode (path is a data directory, created if missing; not a single SQLite file)
seekdb --dsn "embedded:./seekdb.db" status
seekdb --dsn "embedded:~/.seekdb/seekdb.db?database=mydb" sql "SELECT 1"

DSN の形式：

• リモート： seekdb://user:pass@host:port/db
• リモート + TLS： ?tls=skip-verify|required|verify-ca|verify-identity を追加します（または MySQL 形式の sslmode= で同じ値を指定します。例：REQUIRED、VERIFY_CA）。任意のクエリパラメーター：ssl_ca、ssl_cert、ssl_key、ssl_key_password。
• 埋め込み型： embedded:<path>[?database=<db>]（デフォルトの論理データベース名：test）

AI エージェント向けの自己説明

seekdb ai-guide を実行すると、すべてのコマンド、推奨ワークフロー、安全機能、出力形式をまとめた構造化 JSON ガイドを取得できます。CLI 全体を把握するために、一度実行してください。

seekdb ai-guide

推奨ワークフロー

SQL データベースの調査

1. seekdb schema tables              → list all tables (name, column count, row count)
2. seekdb schema describe <table>    → get column names, types, indexes, comments
3. seekdb table profile <table>      → get data statistics (null ratios, distinct, min/max, top values)
4. seekdb relations infer            → infer JOIN relationships between tables
5. seekdb sql "SELECT ... LIMIT N"   → execute SQL with explicit LIMIT

ベクターコレクションのワークフロー

1. seekdb collection list            → list all collections
2. seekdb collection info <name>     → get collection details and preview
3. seekdb query <collection> --text "..." → search (default: hybrid = semantic + fulltext)

コマンドリファレンス

seekdb sql

SQL ステートメントを実行します。デフォルトは読み取り専用モードです。

# Read query
seekdb sql "SELECT id, name FROM users LIMIT 10"

# Read from file
seekdb sql --file query.sql

# Pipe or redirect (stdin read automatically when not a TTY; --stdin is optional)
echo "SELECT 1" | seekdb sql
# Explicit stdin (e.g. redirect into the command)
seekdb sql --stdin < query.sql

# Include table schema in output
seekdb sql "SELECT * FROM orders LIMIT 5" --with-schema

# Disable large-field truncation
seekdb sql "SELECT content FROM articles LIMIT 1" --no-truncate

# Write operation (requires --write flag)
seekdb sql --write "INSERT INTO users (name) VALUES ('Alice')"
seekdb sql --write "UPDATE users SET name = 'Bob' WHERE id = 1"
seekdb sql --write "DELETE FROM users WHERE id = 3"

出力形式：

{"ok": true, "columns": ["id", "name"], "rows": [{"id": 1, "name": "Alice"}], "affected": 0, "time_ms": 12}

seekdb schema tables

seekdb schema tables

{"ok": true, "data": [{"name": "users", "columns": 5, "rows": 1200}, {"name": "orders", "columns": 8, "rows": 50000}]}

seekdb schema describe

seekdb schema describe orders

{"ok": true, "data": {"table": "orders", "comment": "Order table", "columns": [{"name": "id", "type": "int", "comment": "Order ID"}, {"name": "status", "type": "varchar(20)", "comment": "0=pending, 1=paid"}], "indexes": ["PRIMARY(id)", "idx_status(status)"]}}

seekdb schema dump

seekdb schema dump

すべての CREATE TABLE DDL ステートメントを返します。

seekdb table profile

生データを返さずに、テーブルの統計的な概要を生成します。SQL を作成する前に、データの分布を把握するのに役立ちます。

seekdb table profile <table>

{"ok": true, "data": {
  "table": "orders",
  "row_count": 50000,
  "columns": [
    {"name": "id", "type": "int", "null_ratio": 0, "distinct": 50000, "min": 1, "max": 50000},
    {"name": "user_id", "type": "int", "null_ratio": 0, "distinct": 1200, "min": 1, "max": 1500},
    {"name": "amount", "type": "decimal(10,2)", "null_ratio": 0.02, "min": 0.5, "max": 9999.99},
    {"name": "status", "type": "varchar(20)", "null_ratio": 0, "distinct": 4, "top_values": ["paid", "pending", "refunded", "cancelled"]},
    {"name": "created_at", "type": "datetime", "null_ratio": 0, "min": "2024-01-01", "max": "2026-03-10"}
  ],
  "candidate_join_keys": ["user_id"],
  "candidate_time_columns": ["created_at"]
}}

seekdb relations infer

列名のパターン（例：user_id → users.id）と型の互換性を分析し、テーブル間の JOIN 関係を推測します。

# Infer all table relationships
seekdb relations infer

# Infer for a specific table only
seekdb relations infer --table orders

{"ok": true, "data": [
  {"from": "orders.user_id", "to": "users.id", "confidence": "high"},
  {"from": "orders.product_id", "to": "products.id", "confidence": "high"},
  {"from": "order_items.order_id", "to": "orders.id", "confidence": "high"}
]}

seekdb collection list

seekdb collection list

{"ok": true, "data": [{"name": "docs", "count": 1500}, {"name": "faq", "count": 200}]}

seekdb collection create

seekdb collection create my_docs --dimension 384 --distance cosine
seekdb collection create my_docs -d 768 --distance l2

オプション：--dimension / -d（デフォルト：384）、--distance cosine | l2 | ip（デフォルト：cosine）。

seekdb collection delete

seekdb collection delete my_docs

seekdb collection info

seekdb collection info my_docs

{"ok": true, "data": {"name": "my_docs", "count": 1500, "dimension": 384, "distance": "cosine", "preview": {"ids": ["doc1", "doc2"], "documents": ["Hello world", "Test doc"], "metadatas": [{"category": "test"}, {}]}}}

コレクションのメタデータから取得できる場合は、dimension と distance が含まれます。

seekdb query

ハイブリッド（デフォルト）、セマンティック（ベクター）、または全文検索モードを使用して、コレクションを検索します。

# Hybrid search (default: semantic + fulltext, RRF ranking)
seekdb query my_docs --text "how to deploy seekdb"

# Semantic (vector) only
seekdb query my_docs --text "how to deploy seekdb" --mode semantic

# Fulltext search
seekdb query my_docs --text "deployment guide" --mode fulltext

# With metadata filter
seekdb query my_docs --text "performance tuning" --where '{"category": "tech"}'

# Limit results (--limit or -n, default: 10)
seekdb query my_docs --text "seekdb" -n 5

{"ok": true, "data": {"results": [
  {"id": "doc1", "score": 0.92, "document": "How to deploy seekdb...", "metadata": {"category": "tech"}},
  {"id": "doc2", "score": 0.85, "document": "seekdb performance tuning...", "metadata": {"category": "tech"}}
], "count": 2}, "time_ms": 35}

seekdb get

ID またはメタデータフィルターを使って、コレクションからドキュメントを取得します。

# Get by IDs
seekdb get my_docs --ids "doc1,doc2"

# Get by metadata filter (--limit or -n, default: 10)
seekdb get my_docs --where '{"category": "tech"}' -n 20

seekdb add

コレクションにデータを追加します。データソースは --file、--stdin、--data のいずれか1つを指定する必要があります。コレクションが存在しない場合は、自動的に作成されます。

# From file (JSON array, JSONL, or CSV)
seekdb add my_docs --file data.jsonl
seekdb add my_docs --file articles.csv --vectorize-column content

# Inline: single object or array
seekdb add my_docs --data '{"id":"1","document":"Hello world","metadata":{"source":"cli"}}'
seekdb add my_docs --data '[{"id":"a","document":"Doc A"},{"id":"b","document":"Doc B"}]'

# From stdin (JSON array or JSONL; use with pipes)
echo '{"id":"1","document":"from pipe"}' | seekdb add my_docs --stdin
some_script | seekdb add my_docs --stdin

レコード形式：各レコードには、id（任意）、document／text／content（ベクトル化するテキスト）を含めることができ、その他のフィールドはすべてメタデータになります。embedding が指定されている場合は、その値が直接使用されます。

seekdb export

コレクションのデータをファイルにエクスポートします。

seekdb export my_docs --output backup.json
seekdb export my_docs --output backup.jsonl -n 5000

オプション：--output（必須）、--limit / -n（デフォルト：10000）。

seekdb ai model list

データベースに登録されている AI モデルを一覧表示します（DBA_OB_AI_MODELS / DBMS_AI_SERVICE から取得）。リモートモードと組み込みモードの両方で動作します。

seekdb ai model list

{"ok": true, "data": [{"name": "my_llm", "type": "completion", "model_name": "THUDM/GLM-4-9B-0414", "model_id": 1}]}

seekdb ai model create

DBMS_AI_SERVICE.CREATE_AI_MODEL を使用して AI モデルを登録します。補完に使用するには、別途エンドポイントを作成してください。

seekdb ai model create my_llm --type completion --model "THUDM/GLM-4-9B-0414"
seekdb ai model create my_embed --type dense_embedding --model "BAAI/bge-m3"
seekdb ai model create my_rerank --type rerank --model "<rerank_model>"

種類：completion、dense_embedding、rerank。

seekdb ai model delete

AI モデルを削除します。先に、そのモデルを使用するエンドポイントをすべて削除してください。

seekdb ai model delete my_llm

seekdb ai model endpoint create / delete

AI モデルを URL および API キーに紐付けるエンドポイントを作成または削除します（データベースからモデルを呼び出せるようにします）。

seekdb ai model endpoint create my_ep my_llm \
  --url "https://api.siliconflow.cn/v1/chat/completions" \
  --access-key "<YOUR_API_KEY>" \
  --provider siliconflow

seekdb ai model endpoint delete my_ep

サポートされている --provider の値：

Provider	Vendor
siliconflow	SiliconFlow（OpenAI 互換）
openAI	OpenAI
deepseek	DeepSeek（OpenAI 互換）
aliyun-openAI	Alibaba Cloud（OpenAI 互換）
aliyun-dashscope	Alibaba Cloud DashScope
hunyuan-openAI	Tencent Hunyuan（OpenAI 互換）

一般的な --url の値（ベース URL ではなく、用途に応じたインターフェース URL を使用してください）：

Vendor	completion	embedding	rerank
SiliconFlow	https://api.siliconflow.cn/v1/chat/completions	https://api.siliconflow.cn/v1/embeddings	https://api.siliconflow.cn/v1/rerank
DeepSeek	https://api.deepseek.com/chat/completions	—	—
Alibaba (OpenAI)	https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions	https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings	—
Tencent Hunyuan	https://api.hunyuan.cloud.tencent.com/v1/chat/completions	https://api.hunyuan.cloud.tencent.com/v1/embeddings	—

パラメーターの全仕様：CREATE_AI_MODEL_ENDPOINT

seekdb ai complete

データベースの AI_COMPLETE 関数を使用してテキスト補完を実行します。completion モデルとエンドポイントの登録が必要です。リモートモードと組み込みモードの両方でサポートされています。

seekdb ai complete "Summarize this table structure" --model my_llm

{"ok": true, "data": {"model": "my_llm", "response": "The table has..."}, "time_ms": 1200}

seekdb ai-guide

すべてのコマンド、パラメーター、ワークフロー、安全ルールを含む、AI エージェント向けの構造化された JSON ガイドを出力します。一度実行すると、CLI の全機能を確認できます。

seekdb ai-guide

seekdb status

seekdb status

CLI のバージョン、サーバーのバージョン、データベース名、接続状態を返します。

安全機能

行数保護

LIMIT のないクエリは自動的に事前確認されます。結果が 100 行を超える場合、実行はブロックされます。

{"ok": false, "error": {"code": "LIMIT_REQUIRED", "message": "Query returns more than 100 rows. Please add LIMIT to your SQL."}}

対処方法：明示的に LIMIT 句を追加して再試行してください。

書き込み保護

書き込み操作（INSERT/UPDATE/DELETE）は、デフォルトでブロックされます。

{"ok": false, "error": {"code": "WRITE_NOT_ALLOWED", "message": "Write operations require --write flag."}}

対処方法：書き込み操作を有効にするには、--write フラグを追加してください。

--write を指定しても、WHERE 句のない DELETE / UPDATE はブロックされます。

エラーの自動修正

SQL エラーが発生すると、CLI はスキーマのヒントを自動的に付加します。

列が見つからない場合 → テーブルの列一覧とインデックスを返します：

{"ok": false, "error": {"code": "SQL_ERROR", "message": "Unknown column 'username'"}, "schema": {"table": "users", "columns": ["id", "name", "email"], "indexes": ["PRIMARY(id)"]}}

テーブルが見つからない場合 → 利用可能なテーブル名を返します：

{"ok": false, "error": {"code": "SQL_ERROR", "message": "Table 'user' does not exist"}, "schema": {"tables": ["users", "orders", "products"]}}

対処方法：スキーマ情報を使って SQL を修正し、再試行してください。

大きなフィールドの切り詰め

TEXT/BLOB フィールドはデフォルトで 200 文字に切り詰められ、元の長さが表示されます。

{"content": "First 200 characters of content...(truncated, 8520 chars)"}

必要に応じて、--no-truncate を指定すると全内容を取得できます。

機密フィールドのマスキング

機密情報のパターンに一致する列は、自動的にマスキングされます。

パターン	出力例
phone/mobile/tel	138****5678
email	z***@gmail.com
password/secret/api_key	******
id_card / national_id / similar	110***********1234

出力形式

デフォルトは JSON です。--format で切り替えます（グローバルオプションのため、サブコマンドより前に指定してください）。

seekdb --format table sql "SELECT id, name FROM users LIMIT 5"
seekdb --format csv sql "SELECT id, name FROM users LIMIT 5"
seekdb --format jsonl sql "SELECT id, name FROM users LIMIT 5"

すべての形式で、行データ以外（例：schema tables、collection list）も使用できるようになりました。CSV と JSONL は、data フィールド内の辞書のリストを自動的に検出します。

終了コード

コード	意味
0	成功
1	ビジネスエラー（SQL エラー、接続エラーなど）
2	使用方法のエラー（引数の不足、無効なオプション）

操作ログ

すべてのコマンドは監査用に ~/.seekdb/sql-history.jsonl に記録されます（該当する場合、SQL の呼び出しには SQL フィールドがマスキングされて含まれます）。

{"ts": "2026-03-12T14:23:01", "command": "sql", "sql": "SELECT id FROM users LIMIT 10", "ok": true, "rows": 10, "time_ms": 12}