seekdb-cli

seekdb-cli — AI Agent 数据库命令行工具

专为 AI Agent 设计的命令行客户端。所有输出均为 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+；在其他操作系统上，请使用远程 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 Agent 的自描述信息

运行 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。如果集合不存在，则会自动创建。

# 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 值：

服务提供商	厂商
siliconflow	SiliconFlow（兼容 OpenAI）
openAI	OpenAI
deepseek	DeepSeek（兼容 OpenAI）
aliyun-openAI	阿里云（兼容 OpenAI）
aliyun-dashscope	阿里云 DashScope
hunyuan-openAI	腾讯混元（兼容 OpenAI）

常见的 --url 值（请使用具体接口 URL，而非基础 URL）：

厂商	补全	嵌入	重排
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	—	—
阿里云（OpenAI）	https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions	https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings	—
腾讯混元	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 Agent 输出结构化 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}