seekdb

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.

# 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`:

```bash
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](https://www.oceanbase.ai/download) |

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

```bash
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](https://github.com/oceanbase/seekdb-ecology-plugins/tree/main/agent-skills/skills/seekdb/seekdb-docs/400.guides/400.deploy).

## Prerequisites

Check if seekdb-cli is installed:

```bash
seekdb --version
```

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

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

```bash
# 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):**

```bash
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):

```bash
# 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:<path>[?database=<db>]` (default database: `test`)

## Get a Full CLI Guide (run first)

```bash
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.

```bash
# 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:**

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

### seekdb schema tables

```bash
seekdb schema tables
```

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

### seekdb schema describe

```bash
seekdb schema describe orders
```

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

```bash
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.

```bash
seekdb table profile <table>
```

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

Infer JOIN relationships between tables by analyzing column name patterns (e.g., `user_id` → `users.id`) and type compatibility.

```bash
# Infer all table relationships
seekdb relations infer

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

```json
{"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 co