---
name: seekdb-d0
description: Provision a disposable MySQL-compatible database instantly. Returns a short instance_id and one-time password. Instances auto-expire (default 7 days, configurable). Connect via SQL Proxy using standard MySQL clients with username format u_<instance_id>.
compatibility: Requires a MySQL-compatible client or driver (e.g. mysql CLI, mysql2, PyMySQL, go-sql-driver) and network access to the SeekDB D0 SQL Proxy endpoint.
metadata:
  version: 1.0.0
  homepage: https://d0.seekdb.ai
---

# SeekDB D0

Disposable, MySQL-compatible database provisioned via a single unauthenticated API call. No sign-up or billing required. Credentials are returned once at creation and never stored in plaintext. Instances auto-expire (default 7 days).

SeekDB is an AI-native search database: fully MySQL-compatible, with built-in vector search (`VECTOR` type + IVF indexes), full-text search, JSON, and GIS support. Connect through the SQL Proxy using any standard MySQL client or driver.

**When to use:** AI agent memory, MCP server storage, RAG/retrieval demos, temporary sandboxes for tutorials, evals, and short-lived tests.

## Quickstart

### 1. Create an Instance & Import Variables

```bash
eval "$(curl -s -X POST 'https://d0.seekdb.ai/api/v1/instances?format=shell')"
```

### 2. Connect (TLS Required)

```bash
mysql $D0_CONNECTION
```

> **TLS is mandatory.** Plain TCP connections are rejected at the TLS handshake. Every connection example below includes the required TLS flag.
>
> `?format=shell` returns `export` statements you can `eval` directly. Omit `?format=shell` (or use `?format=json`) to get the default JSON response.

### 3. Verify

```sql
SELECT 'Hello from SeekDB D0!' AS message, NOW() AS server_time;
```

## API Reference

### Create Instance

**POST** `https://d0.seekdb.ai/api/v1/instances[?format=shell]`

No request body. Rate limited (global QPS + per-IP per-minute/hour limits).

| Query param | Effect |
|-------------|--------|
| *(none)* or `format=json` | JSON response (default) |
| `format=shell` | Plain-text `export` statements, ready for `eval` |

**Response (201) — JSON (default):**

```json
{
  "instance_id": "aB3kR7mN2pQx",
  "username": "u_aB3kR7mN2pQx",
  "password": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "database": "d0_aB3kR7mN2pQx",
  "host": "gw0.apac.seekdb.ai",
  "port": "2881",
  "expires_at": "2026-04-28T00:00:00Z",
  "connection": "mysql://u_aB3kR7mN2pQx:xxxx@gw0.apac.seekdb.ai:2881/d0_aB3kR7mN2pQx",
  "connection_string": "-h gw0.apac.seekdb.ai -P 2881 -u u_aB3kR7mN2pQx -p\"xxxx\" --ssl-mode=REQUIRED d0_aB3kR7mN2pQx"
}
```

| Field | Description |
|-------|-------------|
| `instance_id` | 12-char alphanumeric routing ID |
| `username` | MySQL username: `u_<instance_id>` (matches `SELECT USER()`) |
| `password` | **One-time only.** Never retrievable again — store it immediately. |
| `database` | Assigned database: `d0_<instance_id>` |
| `host` / `port` | SQL Proxy endpoint |
| `expires_at` | Instance expiry (ISO 8601 UTC) |
| `connection` | Ready-to-use MySQL DSN |
| `connection_string` | mysql CLI connection arguments (copy-paste friendly) |

> **Instance TTL:** 7 days (default, operator-configurable). After expiry the instance and all its data are permanently deleted.

### Fork Instance (clone the entire database)

**POST** `https://d0.seekdb.ai/api/v1/instances/{instance_id}/fork`

Creates a new instance that is a copy-on-write clone of the source instance's **entire database** (millisecond-level via SeekDB native `FORK DATABASE`). The new instance gets its own credentials, is fully independent, and writes do not affect the source.

> This is different from `FORK TABLE`, which clones a single table *within* the same instance via SQL. See [seekdb-branch](https://d0.seekdb.ai/skills/seekdb-branch.md) for `FORK TABLE`.

**Request body (required):**

```json
{"password": "<source_instance_password>"}
```

**Response (201):** Same format as Create Instance.

**Constraints:**
- Source instance must be `active`
- Max 5 instances per lineage tree (root + all descendants)
- Fork must occur on the same SeekDB node as the source

**Error responses:**

| HTTP | `error` field | Meaning |
|------|--------------|---------|
| 400 | `password_required` | Missing `password` in request body |
| 401 | `access_denied` | Password does not match source instance |
| 404 | `instance_not_found` | Source instance does not exist |
| 409 | `instance_not_active` | Source instance is expired or being recycled |
| 409 | `lineage_limit_exceeded` | Lineage tree already at max instances |
| 503 | `no_fork_capacity` | Source node's fork slots exhausted |
| 500 | *(message)* | Internal error |

**Example:**

```bash
# Shell format — eval to import D0_* variables for the fork
eval "$(curl -s -X POST 'https://d0.seekdb.ai/api/v1/instances/'$D0_INSTANCE_ID'/fork?format=shell' \
  -H 'Content-Type: application/json' \
  -d "{\"password\": \"$D0_PASSWORD\"}")"

mysql $D0_CONNECTION
```

## Driver Connection Examples

All connections require TLS. Examples below show the TLS flag for each driver.

### Python (PyMySQL)

```python
import pymysql
conn = pymysql.connect(
    host='gw0.apac.seekdb.ai', port=2881,
    user='u_<instance_id>', password='<password>',
    database='d0_<instance_id>',
    ssl={'ssl': True}   # add ssl_ca='/path/ca.pem' for CA verification
)
```

### Node.js (mysql2)

```javascript
const mysql = require('mysql2/promise');
const conn = await mysql.createConnection({
    host: 'gw0.apac.seekdb.ai', port: 2881,
    user: 'u_<instance_id>', password: '<password>',
    database: 'd0_<instance_id>',
    ssl: { rejectUnauthorized: false }  // set true + ca for CA-signed cert
});
```

### Go (go-sql-driver/mysql)

```go
import "database/sql"
import _ "github.com/go-sql-driver/mysql"

// Self-signed cert: tls=skip-verify
db, err := sql.Open("mysql",
    "u_<instance_id>:<password>@tcp(gw0.apac.seekdb.ai:2881)/d0_<instance_id>?tls=skip-verify")

// CA-signed cert: tls=true
db, err := sql.Open("mysql",
    "u_<instance_id>:<password>@tcp(gw0.apac.seekdb.ai:2881)/d0_<instance_id>?tls=true")
```

### Java (JDBC)

```java
String url = "jdbc:mysql://gw0.apac.seekdb.ai:2881/d0_<instance_id>"
           + "?useSSL=true&verifyServerCertificate=false";
Connection conn = DriverManager.getConnection(url, "u_<instance_id>", "<password>");
```

## HTTP Query API (Convenience)

> **For temporary / low-frequency use only.** This endpoint has strict rate limits. For production workloads or sustained queries, connect via the MySQL protocol instead (see Driver Connection Examples above).

Execute a single SQL statement over HTTP without a MySQL client or driver. Useful for quick debugging, one-off queries from scripts, or environments where installing a MySQL driver is impractical.

### Endpoint

**POST** `https://d0.seekdb.ai/api/v1/query`

### Request

```json
{
  "instance_id":     "<instance_id>",
  "password":        "<password>",
  "sql":             "SELECT 1",
  "params":          [],
  "timeout_seconds": 30,
  "max_rows":        100
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `instance_id` | Yes | The 12-char instance ID |
| `password` | Yes | Instance password (the one returned at creation) |
| `sql` | Yes | SQL statement to execute |
| `params` | No | Bind parameters for parameterized queries |
| `timeout_seconds` | No | Query timeout, default 30, max 60 |
| `max_rows` | No | Max rows returned, default/max 10 000 |

### Response

**SELECT queries (200):**

```json
{
  "columns":      ["col1", "col2"],
  "column_types": ["VARCHAR", "INT"],
  "rows":         [["val1", 1], ["val2", 2]],
  "row_count":    2,
  "elapsed_ms":   5
}
```

**DML/DDL statements (200):**

```json
{
  "affected_rows":  1,
  "last_insert_id": 42,
  "elapsed_ms":     3
}
```

### Error responses

| HTTP | `error` field | Meaning |
|------|---------------|---------|
| 400 | `invalid_request` | Missing required field |
| 401 | `access_denied` | Wrong password |
| 403 | `sql_blocked` | SQL matched server-side blocklist |
| 404 | `instance_not_found` | Unknown instance ID |
| 429 | `rate_limit_exceeded` | Global QPS limit reached |
| 429 | `instance_rate_limit_exceeded` | Per-instance QPM limit reached |
| 429 | `blocked` | Too many auth failures (brute-force protection) |
| 500 | `query_error` | SQL execution error |

### Example

```bash
curl -s -X POST https://d0.seekdb.ai/api/v1/query \
  -H 'Content-Type: application/json' \
  -d "{
    \"instance_id\": \"$D0_INSTANCE_ID\",
    \"password\":    \"$D0_PASSWORD\",
    \"sql\":         \"SELECT NOW() AS server_time\"
  }"
```

## Vector Search

SeekDB D0 supports vector search with IVF indexes. Create a table with a `VECTOR` column, build an index, and query by distance.

### Create a vector table

```sql
CREATE TABLE documents (
    id INT PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(256),
    content TEXT,
    embedding VECTOR(768),
    VECTOR INDEX idx_emb(embedding) WITH(DISTANCE=l2, TYPE=ivf_flat, LIB=ob)
);
```

### Insert vectors

```sql
INSERT INTO documents (title, content, embedding) VALUES
    ('AI Intro', 'Fundamentals of AI', '[0.1, 0.2, ...]');
```

### Query by similarity

```sql
SELECT id, title, l2_distance(embedding, '[0.1, 0.2, ...]') AS dist
FROM documents
ORDER BY dist
LIMIT 10;
```

### Available IVF index types

| Type | Precision | Storage | Best for |
|------|-----------|---------|----------|
| `IVF_FLAT` | Highest | Original size | Small datasets, high precision (default) |
| `IVF_SQ8` | High | ~1/4 | Balance precision and storage |
| `IVF_PQ` | Medium | Smallest | Large datasets, storage-sensitive |

> HNSW/HGRAPH indexes are **not available** in Anon mode. Use IVF series only.

## Usage Policy

- **No stress testing or benchmarking.** Do not run load tests, concurrent connection floods, or high-QPS benchmarks against SeekDB D0. Instances are shared infrastructure with strict rate limits.
- **No malicious activity.** Do not attempt SQL injection attacks, privilege escalation, unauthorized data access, denial-of-service, or any form of abuse. Violations will result in immediate IP ban.

## Fork Instance vs FORK TABLE

| | Fork Instance (API) | FORK TABLE (SQL) |
|---|---|---|
| **Scope** | Clones the **entire database** into a new instance | Clones a **single table** within the same instance |
| **How** | `POST /api/v1/instances/{id}/fork` | `FORK TABLE src_table TO new_table` (SQL statement) |
| **Result** | New instance with new credentials | New table in the same database |
| **Use case** | Snapshot whole environment, parallel experiments | Branch one table for A/B testing, safe schema changes |
| **Docs** | This document (above) | [seekdb-branch](https://d0.seekdb.ai/skills/seekdb-branch.md) |

## Resources

- SeekDB D0 API: `https://d0.seekdb.ai/api/v1/instances`
- HTTP Query API: `https://d0.seekdb.ai/api/v1/query` — execute SQL over HTTP (convenience, rate-limited)
- [seekdb-cli](https://d0.seekdb.ai/skills/seekdb-cli.md) — AI-Agent-friendly database CLI with JSON output, SQL/schema/vector commands, and built-in safety guardrails.
- [seekdb-search](https://d0.seekdb.ai/skills/seekdb-search.md) — Vector similarity search and full-text retrieval using SeekDB's built-in IVF indexes and collection API.
- [seekdb-branch](https://d0.seekdb.ai/skills/seekdb-branch.md) — Copy-on-write data branching: FORK TABLE for instant table clones, DIFF to compare, MERGE to reconcile diverged branches.