chore: unify env to SEEKDB_*, document OceanBase/tenant, reorder examples (embedded first), expand Packages, remove TEST_CONFIG_OB

Author: dengfuping

.env.example

@@ -1,2 +1,9 @@
 # DASHSCOPE_API_KEY=your_qwen_api_key_here
 # OPENAI_API_KEY=your_qwen_api_key_here
+
+# Server-mode tests / examples (optional; defaults: host=127.0.0.1, port=2881, user=root, database=test)
+# SEEKDB_HOST=127.0.0.1
+# SEEKDB_PORT=2881
+# SEEKDB_USER=root
+# SEEKDB_PASSWORD=
+# SEEKDB_DATABASE=test

.github/workflows/ci.yml

@@ -99,12 +99,11 @@ jobs:
       - name: Run server tests
         working-directory: packages/seekdb
         env:
-          SERVER_HOST: 127.0.0.1
-          SERVER_PORT: 2881
-          SERVER_USER: root
-          SERVER_PASSWORD: ""
-          SERVER_DATABASE: test
-          SERVER_TENANT: sys
+          SEEKDB_HOST: 127.0.0.1
+          SEEKDB_PORT: 2881
+          SEEKDB_USER: root
+          SEEKDB_PASSWORD: ""
+          SEEKDB_DATABASE: test
         run: pnpm exec vitest run --exclude 'tests/embedded/**'
 
   # Embedded-mode tests on multiple platforms (requires native bindings build per OS; Docker per job)
@@ -162,12 +161,11 @@ jobs:
       - name: Run embedded tests
         working-directory: packages/seekdb
         env:
-          SERVER_HOST: 127.0.0.1
-          SERVER_PORT: 2881
-          SERVER_USER: root
-          SERVER_PASSWORD: ""
-          SERVER_DATABASE: test
-          SERVER_TENANT: sys
+          SEEKDB_HOST: 127.0.0.1
+          SEEKDB_PORT: 2881
+          SEEKDB_USER: root
+          SEEKDB_PASSWORD: ""
+          SEEKDB_DATABASE: test
         run: |
           if [ "$RUNNER_OS" = "Linux" ]; then
             pnpm exec vitest run tests/embedded/ 2>&1 | tee /tmp/vitest.log

DEVELOP.md

@@ -115,7 +115,7 @@ pnpm --filter seekdb exec vitest run tests/embedded/
 **Tests and running mode**:
 
 - **Embedded-mode tests** live under `packages/seekdb/tests/embedded/` and use a temporary database path per test file. They do not require a seekdb/OceanBase server.
-- **Server-mode tests** (under `packages/seekdb/tests/` but outside `embedded/`) connect to `127.0.0.1:2881` and require a local seekdb or OceanBase instance.
+- **Server-mode tests** (under `packages/seekdb/tests/` but outside `embedded/`) connect to `127.0.0.1:2881` and require a local seekdb or OceanBase instance. Override with `SEEKDB_HOST`, `SEEKDB_PORT`, `SEEKDB_USER`, `SEEKDB_PASSWORD`, `SEEKDB_DATABASE`.
 - **Mode consistency** tests (`tests/embedded/mode-consistency.test.ts`) run both embedded and server modes; they require the native addon and a server for the server part.
 - Embedded test coverage vs server is documented in `packages/seekdb/tests/embedded/COVERAGE_REPORT.md`.
 

README.md

@@ -36,11 +36,26 @@ For complete usage, please refer to the official documentation.
 
 This is a monorepo containing:
 
-| Package                  | Description                                                                                                 |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
-| `seekdb`                 | Core SDK for seekdb operations                                                                              |
-| `@seekdb/prisma-adapter` | Prisma driver adapter for seekdb Embedded (use Prisma ORM with no MySQL server)                             |
-| `embeddings`             | Several embedding functions we provide, including local default-embed, OpenAI embedding, Ollama, Jina, etc. |
+| Package                        | Description                                                                                                     |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| **Core**                       |                                                                                                                 |
+| `seekdb`                       | Core SDK for seekdb (Embedded + Server mode), collections, vector/hybrid search, raw SQL via `client.execute()` |
+| `@seekdb/js-bindings`          | Native addon for Embedded mode; optional dependency of `seekdb`, can be loaded on demand                        |
+| **Integrations**               |                                                                                                                 |
+| `@seekdb/prisma-adapter`       | Prisma driver adapter for seekdb Embedded (use Prisma with seekdb Embedded)                                     |
+| **Embedding packages**         |                                                                                                                 |
+| `@seekdb/default-embed`        | Default local embedding (e.g. Xenova/all-MiniLM-L6-v2), no API key; recommended for getting started             |
+| `@seekdb/ollama`               | Ollama local embedding                                                                                          |
+| `@seekdb/sentence-transformer` | Sentence Transformer local models                                                                               |
+| `@seekdb/openai`               | OpenAI embedding API                                                                                            |
+| `@seekdb/qwen`                 | Alibaba DashScope / Qwen embedding API                                                                          |
+| `@seekdb/jina`                 | Jina AI embedding API                                                                                           |
+| `@seekdb/cohere`               | Cohere embedding API                                                                                            |
+| `@seekdb/voyageai`             | Voyage AI embedding API                                                                                         |
+| `@seekdb/amazon-bedrock`       | AWS Bedrock embedding                                                                                           |
+| `@seekdb/google-vertex`        | Google Vertex AI embedding                                                                                      |
+| `@seekdb/siliconflow`          | SiliconFlow embedding API                                                                                       |
+| `@seekdb/tencent-hunyuan`      | Tencent Hunyuan embedding API                                                                                   |
 
 ## Installation
 
@@ -60,22 +75,21 @@ The SDK supports two modes; the constructor arguments to `SeekdbClient` determin
 | **Embedded** | `path` (database directory path)              | Runs locally with no separate seekdb server; data is stored under the given path (e.g. `./seekdb.db`). Requires native addon `@seekdb/js-bindings`. |
 | **Server**   | `host` (and `port`, `user`, `password`, etc.) | Connects to a remote seekdb or OceanBase instance.                                                                                                  |
 
+**OceanBase and seekdb**: OceanBase is compatible with seekdb and can be understood as its distributed, multi-tenant, etc. version. seekdb-js therefore supports **OceanBase server mode** with the same API: use the same `SeekdbClient` / `AdminClient` and connection parameters; when connecting to OceanBase, additionally pass `tenant` (e.g. `"sys"` or your tenant name). See [OceanBase mode](#oceanbase-mode-server-mode-with-tenant) below.
+
 - **SeekdbClient**: Pass `path` for embedded mode, or `host` (and port, user, password, etc.) for server mode.
 - **AdminClient()**: For admin operations only; pass `path` for embedded or `host` for server. In embedded mode you do not specify a database name.
 
 ## Quick Start
 
-**Server mode** (connect to a deployed seekdb):
+**Embedded mode** (local file, no server):
 
 ```typescript
 import { SeekdbClient } from "seekdb";
 
 // 1. Connect
 const client = new SeekdbClient({
-  host: "127.0.0.1",
-  port: 2881,
-  user: "root",
-  password: "",
+  path: "./seekdb.db",
   database: "test",
 });
 
@@ -93,14 +107,17 @@ const results = await collection.query({ queryTexts: "Hello", nResults: 5 });
 console.log("query results", results);
 ```
 
-**Embedded mode** (local file, no server):
+**Server mode** (connect to a deployed seekdb):
 
 ```typescript
 import { SeekdbClient } from "seekdb";
 
 // 1. Connect
 const client = new SeekdbClient({
-  path: "./seekdb.db",
+  host: "127.0.0.1",
+  port: 2881,
+  user: "root",
+  password: "",
   database: "test",
 });
 
@@ -124,7 +141,18 @@ console.log("query results", results);
 
 ### Client Connection
 
-**Server mode** (seekdb / OceanBase):
+**Embedded mode** (local database file):
+
+```typescript
+import { SeekdbClient } from "seekdb";
+
+const client = new SeekdbClient({
+  path: "./seekdb.db", // database file path
+  database: "test",
+});
+```
+
+**Server mode**:
 
 ```typescript
 import { SeekdbClient } from "seekdb";
@@ -135,19 +163,19 @@ const client = new SeekdbClient({
   user: "root",
   password: "",
   database: "test",
-  // Required for OceanBase mode
-  // tenant: "sys",
 });
 ```
 
-**Embedded mode** (local database file):
+**OceanBase mode** (server mode with tenant): OceanBase is compatible with seekdb (distributed, multi-tenant, etc.). Use the same server-mode connection; when the backend is OceanBase, pass `tenant` (e.g. `"sys"` or your tenant name):
 
 ```typescript
-import { SeekdbClient } from "seekdb";
-
 const client = new SeekdbClient({
-  path: "./seekdb.db", // database file path
+  host: "127.0.0.1",
+  port: 2881,
+  user: "root",
+  password: "",
   database: "test",
+  tenant: "sys", // or your OceanBase tenant
 });
 ```
 
@@ -444,6 +472,19 @@ const collection = await client.createCollection({
 
 Use `AdminClient()` for database management. It returns a `SeekdbClient` instance. In **embedded mode** you only pass `path`; no database name is required.
 
+**Embedded mode** (local database file):
+
+```typescript
+import { AdminClient } from "seekdb";
+
+const admin = AdminClient({ path: "./seekdb.db" });
+await admin.createDatabase("new_database");
+const databases = await admin.listDatabases();
+const db = await admin.getDatabase("new_database");
+await admin.deleteDatabase("new_database");
+await admin.close();
+```
+
 **Server mode**:
 
 ```typescript
@@ -454,7 +495,6 @@ const admin = AdminClient({
   port: 2881,
   user: "root",
   password: "",
-  // OceanBase mode requires tenant: "sys"
 });
 
 await admin.createDatabase("new_database");
@@ -464,12 +504,17 @@ await admin.deleteDatabase("new_database");
 await admin.close();
 ```
 
-**Embedded mode** (no server):
+**OceanBase mode** (server mode with tenant): add `tenant` (e.g. `"sys"` or your tenant name) to the config:
 
 ```typescript
-import { AdminClient } from "seekdb";
+const admin = AdminClient({
+  host: "127.0.0.1",
+  port: 2881,
+  user: "root",
+  password: "",
+  tenant: "sys", // or your OceanBase tenant
+});
 
-const admin = AdminClient({ path: "./seekdb.db" });
 await admin.createDatabase("new_database");
 const databases = await admin.listDatabases();
 const db = await admin.getDatabase("new_database");

examples/complete-example.ts

@@ -33,7 +33,7 @@ async function main() {
   //   database: "test",
   //   user: "root",
   //   password: "",
-  //   // for OceanBase, set tenant to "sys"
+  //   // For OceanBase: add tenant: "sys" or your tenant.
   //   // tenant: "sys",
   // });
 

examples/hybrid-search-example.ts

@@ -26,7 +26,7 @@ async function main() {
   //   database: "test",
   //   user: "root",
   //   password: "",
-  //   // for OceanBase, set tenant to "sys"
+  //   // For OceanBase: add tenant: "sys" or your tenant.
   //   // tenant: "sys",
   // });
 

examples/seekdb-prisma/README.md

@@ -3,7 +3,7 @@
 Vector/hybrid search with seekdb-js and type-safe relational tables with Prisma.
 
 - **Server mode** (`pnpm start`): same database, two connections (SeekdbClient + PrismaClient via `DATABASE_URL`).
-- **Embedded mode** (`pnpm run start:embedded`): use [@seekdb/prisma-adapter](https://www.npmjs.com/package/@seekdb/prisma-adapter) so Prisma runs SQL via `client.execute()` — no MySQL server.
+- **Embedded mode** (`pnpm run start:embedded`): use [@seekdb/prisma-adapter](https://www.npmjs.com/package/@seekdb/prisma-adapter) so Prisma runs SQL via `client.execute()`.
 
 ## Prerequisites
 

examples/simple-example.ts

@@ -31,7 +31,7 @@ async function main() {
   //   database: "test",
   //   user: "root",
   //   password: "",
-  //   // for OceanBase, set tenant to "sys"
+  //   // For OceanBase: add tenant: "sys" or your tenant.
   //   // tenant: "sys",
   // });
 

packages/prisma-adapter/README.md

@@ -1,6 +1,6 @@
 # @seekdb/prisma-adapter
 
-Prisma driver adapter for **seekdb Embedded**. Use Prisma ORM with seekdb in-process — no MySQL server required.
+Prisma driver adapter for **seekdb Embedded**. Use Prisma with seekdb Embedded.
 
 - **Provider**: `mysql` (seekdb is MySQL-compatible)
 - **Use case**: Vector/hybrid search with seekdb Collection API + type-safe relational tables with Prisma, all in one embedded database file.

packages/prisma-adapter/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seekdb/prisma-adapter",
   "version": "0.1.0",
-  "description": "Prisma driver adapter for seekdb Embedded — use Prisma with seekdb in-process (no MySQL server)",
+  "description": "Prisma driver adapter for seekdb Embedded — use Prisma with seekdb Embedded",
   "keywords": [
     "seekdb",
     "prisma",