--- name: seekdb description: "Operate seekdb via CLI commands and look up seekdb documentation. Use when: executing SQL, exploring table schemas, managing vector collections, registering AI models, answering user questions about seekdb, or looking up seekdb concepts and syntax. Triggers on: SQL queries, database operations, seekdb features, vector/hybrid/semantic search questions, or any user question about seekdb. Supports both embedded mode and remote server mode." license: MIT ---

seekdb — AI-Agent Database CLI with Documentation

This skill lets AI Agents operate seekdb via seekdb-cli commands and look up seekdb documentation when needed.

> Quick orientation: Start with seekdb ai-guide to get a full JSON self-description of the CLI. Then run commands directly — no setup needed.

---

Part 1: seekdb-cli Operations

seekdb-cli is purpose-built for AI Agents. All output is structured JSON, all operations are stateless, and built-in safety guardrails prevent accidental data loss.

seekdb Deployment

seekdb supports two modes. Use this section to guide users to the right deployment path based on their OS and scenario.

Embedded Mode

seekdb runs as a library inside the application — no server process required. Install via pyseekdb:

pip install -U pyseekdb

Supported platforms: Linux (glibc ≥ 2.28), macOS 15+ · Architectures: x86_64, aarch64

> Windows and older macOS versions do not support embedded mode. Use server mode instead.

Server Mode

A persistent seekdb process, connectable via MySQL client or seekdb-cli (remote DSN). Choose by OS:

| OS | Recommended method | Quick start | |----|--------------------|-------------| | Linux (CentOS/RHEL/Anolis/openEuler) | Package manager (RPM) | curl -fsSL https://obportal.s3.ap-southeast-1.amazonaws.com/download-center/opensource/seekdb/seekdb_install.sh \| sudo bash | | Linux (Debian/Ubuntu) | Package manager (DEB) | sudo apt update && sudo apt install seekdb | | macOS 15+ | Homebrew | brew tap oceanbase/seekdb && brew install seekdb | | Any OS with Docker | Docker | docker run -d -p 2881:2881 oceanbase/seekdb | | Windows / macOS (GUI) | OceanBase Desktop | Download from oceanbase.ai/download |

Connect after server mode deployment (default port 2881, user root, empty password):

mysql -h127.0.0.1 -uroot -P2881 -A -Dtest
# or via seekdb-cli:
seekdb --dsn "seekdb://root:@127.0.0.1:2881/test" status

Minimum requirements: 1 CPU core, 2 GB RAM, SSD storage.

For full deployment details, see the deployment docs.

Prerequisites

Check if seekdb-cli is installed:

seekdb --version

If not installed, choose the method that matches your environment:

Recommended — pipx (works globally without polluting system Python):

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

Alternative — pip (when inside a project venv or on systems without PEP 668):

pip install seekdb-cli

> Note for Ubuntu 23.04+ / Debian 12+: Direct pip install at the system level is blocked by PEP 668. > Use pipx instead — it creates an isolated environment while keeping the seekdb command globally available on your PATH.

Connection

seekdb-cli auto-discovers the connection (env var, .env, ~/.seekdb/config.env, or default ~/.seekdb/seekdb.db). No setup needed — just run commands directly.

If the user provides a specific DSN, pass it via --dsn (must appear before the subcommand):

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

# Embedded mode (local database file)
seekdb --dsn "embedded:./seekdb.db" status
seekdb --dsn "embedded:~/.seekdb/seekdb.db?database=mydb" sql "SELECT 1"

DSN formats:

• Remote: seekdb://user:pass@host:port/db
• Embedded: embedded:[?database=] (default database: test)

Get a Full CLI Guide (run first)

seekdb ai-guide

Returns a structured JSON document with every command, parameter, workflow, safety rules, and output format. Run this once at the start of any seekdb task to orient yourself.

Recommended Workflows

SQL Database Exploration

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>      → 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

Vector Collection Workflow

1. seekdb collection list            → list all collections
2. seekdb collection info <name>     → collection details and document preview
3. seekdb query <collection> --text "..." → hybrid search (default: semantic + fulltext)
4. seekdb add <collection> --data '...'  → add new documents

AI Model Setup Workflow

1. seekdb ai model list                                    → check registered models
2. seekdb ai model create <name> --type <type> --model <model_name>
3. seekdb ai model endpoint create <ep> <model> --url <url> --access-key <key>
4. seekdb ai complete "<prompt>" --model <name>           → test completion

Command Reference

seekdb sql

Execute SQL statements. Default is read-only mode.

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

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

# Read from stdin
echo "SELECT 1" | seekdb sql --stdin

# 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"

Output format:

{"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

Returns all CREATE TABLE DDL statements.

seekdb table profile

Generate statistical summary of a table without returning raw data. Helps understand data distribution before writing 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

...