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

INLINECODE2 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:

CODEBLOCK0

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:

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

CODEBLOCK1

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:

CODEBLOCK2

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

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

CODEBLOCK3

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

CODEBLOCK4

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

CODEBLOCK5

DSN formats:

• - Remote: INLINECODE16
• Embedded: embedded:<path>[?database=<db>] (default database: test)

Get a Full CLI Guide (run first)

CODEBLOCK6

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

CODEBLOCK7

Vector Collection Workflow

CODEBLOCK8

AI Model Setup Workflow

CODEBLOCK9

Command Reference

seekdb sql

Execute SQL statements. Default is read-only mode.

CODEBLOCK10

Output format:

CODEBLOCK11

seekdb schema tables

CODEBLOCK12

CODEBLOCK13

seekdb schema describe

CODEBLOCK14

CODEBLOCK15

seekdb schema dump

CODEBLOCK16

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.

CODEBLOCK17

CODEBLOCK18

seekdb relations infer

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

CODEBLOCK19

CODEBLOCK20

seekdb collection list

CODEBLOCK21

CODEBLOCK22

seekdb collection create

CODEBLOCK23

Options: --dimension / -d (default: 384), --distance cosine | l2 | ip (default: cosine).

seekdb collection delete

CODEBLOCK24

seekdb collection info

CODEBLOCK25

CODEBLOCK26

INLINECODE25 and distance are included when available from the collection metadata.

seekdb query

Search a collection using hybrid (default), semantic (vector), or fulltext mode.

CODEBLOCK27

CODEBLOCK28

seekdb get

Retrieve documents from a collection by IDs or metadata filter.

CODEBLOCK29

seekdb add

Add data to a collection. Exactly one source is required: --file, --stdin, or --data. The collection is auto-created if it does not exist.

CODEBLOCK30

Record format: Each record may have id (optional), document/text/content (text to vectorize), and any other fields become metadata. If embedding is present, it is used directly.

seekdb export

Export collection data to a file.

CODEBLOCK31

Options: --output (required), --limit / -n (default: 10000).

seekdb ai model list

List AI models registered in the database (from DBA_OB_AI_MODELS / DBMSAISERVICE). Works in both remote and embedded mode.

CODEBLOCK32

CODEBLOCK33

seekdb ai model create

Register an AI model via DBMS_AI_SERVICE.CREATE_AI_MODEL. Create an endpoint separately to use it for completion.

CODEBLOCK34

Types: completion, dense_embedding, rerank.

seekdb ai model delete

Drop an AI model. Drop any endpoints that use it first.

CODEBLOCK35

seekdb ai model endpoint create / delete

Create or drop an endpoint that binds an AI model to a URL and API key (so the database can call the model).

CODEBLOCK36

Supported --provider values:

Common --url values (use the specific interface URL, not the base URL):

seekdb ai complete

Run text completion using the database AI_COMPLETE function. Requires a registered completion model and an endpoint. Supported in both remote and embedded mode.

CODEBLOCK37

CODEBLOCK38

seekdb ai-guide

Output a structured JSON guide for AI Agents containing all commands, parameters, workflow, and safety rules. Execute once to learn the full CLI.

CODEBLOCK39

seekdb status

CODEBLOCK40

Returns CLI version, server version, database name, and connectivity.

Safety Features

Row Protection

Queries without LIMIT are automatically probed. If result exceeds 100 rows, execution is blocked:

CODEBLOCK41

Action: Add an explicit LIMIT clause and retry.

Write Protection

Write operations (INSERT/UPDATE/DELETE) are blocked by default:

CODEBLOCK42

Action: Add --write flag to enable write operations.

Even with --write, these are always blocked:

• - DELETE / UPDATE without WHERE clause
• INLINECODE67 / TRUNCATE statements

Error Auto-Correction

On SQL errors, the CLI automatically attaches schema hints:

Column not found → returns the table's column list and indexes:
CODEBLOCK43

Table not found → returns available table names:
CODEBLOCK44

Action: Use the schema info to correct the SQL and retry.

Large Field Truncation

TEXT/BLOB fields are truncated to 200 characters by default, with original length noted:

CODEBLOCK45

Use --no-truncate to get full content when needed.

Sensitive Field Masking

Columns matching sensitive patterns are automatically masked:

Output Formats

Default is JSON. Switch with --format / -f:

CODEBLOCK46

All formats now work with non-row data (e.g., schema tables, collection list). CSV and JSONL will auto-detect list-of-dict data in the data field.

Exit Codes

Operation Logging

All commands are logged to ~/.seekdb/sql-history.jsonl (seekdb-cli SQL execution history) for audit:

CODEBLOCK47

Part 2: Documentation Lookup

Use documentation lookup when you need to understand a seekdb concept, look up SQL syntax, find configuration details, or answer user questions about seekdb.

Tip: For live database state (tables, schemas, data), run CLI commands directly. For concepts, syntax, and how-to guidance, search the docs.

When to Use Documentation Lookup

• - Need to understand a seekdb concept (vector search, hybrid search, HNSW index, etc.)
• Need SQL or PL syntax reference not answerable by seekdb schema commands
• Need deployment, configuration, or integration guidance
• CLI returned an error and you need to understand why from the docs

Path Resolution

1. 1. Read this SKILL.md to get its absolute path and extract the parent directory as INLINECODE81
2. Catalog: INLINECODE82

Documentation Workflow

Step 1: Search Catalog

Search the catalog file for lines containing the query keywords. Each line is one JSON object with path, description, and branch.

CODEBLOCK48

Step 2: Match Query

• - Extract path, description, and branch from search results
• Select entries whose descriptions best match the query semantically
• Consider multiple matches for comprehensive answers

Step 3: Fetch Document

Fetch the document from the public docs URL:

• - URL: INLINECODE90
• INLINECODE91 and [path] come from the catalog entry (e.g., V1.0.0, V1.1.0)

Example

CODEBLOCK49

See references/doc-examples.md for more workflow examples.

If the information you need cannot be found in the catalog or the CLI output, visit the official seekdb documentation at oceanbase.ai/docs for the most complete and up-to-date reference.