diff --git a/README.md b/README.md index f1b22bdd..4a1c321c 100644 --- a/README.md +++ b/README.md @@ -24,17 +24,17 @@ ```bash +------------------+ +--------------+ +------------------+ | | | | | | - | | | | | | | Claude Desktop +--->+ +--->+ PostgreSQL | | | | | | | | Claude Code +--->+ +--->+ SQL Server | | | | | | | - | Cursor +--->+ DBHub +--->+ SQLite | + | Cursor +--->+ DBHub +--->+ Oracle | | | | | | | - | VS Code +--->+ +--->+ MySQL | + | VS Code +--->+ +--->+ SQLite | | | | | | | - | Copilot CLI +--->+ +--->+ MariaDB | + | Copilot CLI +--->+ +--->+ MySQL | | | | | | | + | | | +--->+ MariaDB | | | | | | | +------------------+ +--------------+ +------------------+ MCP Clients MCP Server Databases diff --git a/docs/config/command-line.mdx b/docs/config/command-line.mdx index c5226848..c82f305d 100644 --- a/docs/config/command-line.mdx +++ b/docs/config/command-line.mdx @@ -211,6 +211,27 @@ This page covers command-line flags and environment variables. For TOML configur + + ```bash + # Format: oracle://[user]:[password]@[host]:[port]/[service_name]?[options] + oracle://app:secret@localhost:1521/FREEPDB1 + + # Old-style SID instead of a service name + oracle://app:secret@localhost:1521/?sid=ORCL + + # TCPS (TLS): require = encrypted, verify-full = certificate DN matched against the host + oracle://app:secret@db.example.com:2484/PROD?sslmode=verify-full + ``` + + + The path is the **service name** (e.g. `FREEPDB1` on Oracle Database + Free). DBHub uses node-oracledb in Thin mode, so no Oracle Instant + Client is needed. `verify-full` validates the server certificate + against the system trust store; `sslrootcert` is not supported for + Oracle. + + + ```bash # Format: sqlite:///[path/to/database.db] or sqlite:///:memory: @@ -231,11 +252,12 @@ This page covers command-line flags and environment variables. For TOML configur | Parameter | Databases | Description | Example | |-----------|-----------|-------------|---------| - | `sslmode` | PostgreSQL, MySQL, MariaDB, SQL Server | SSL mode: `disable`, `require`, `verify-ca`, `verify-full` | `?sslmode=require` | + | `sslmode` | PostgreSQL, MySQL, MariaDB, SQL Server, Oracle | SSL mode: `disable`, `require`, `verify-ca`, `verify-full` | `?sslmode=require` | | `sslrootcert` | PostgreSQL | CA certificate path (requires `verify-ca` or `verify-full`) | `?sslrootcert=~/.ssl/ca.pem` | | `instanceName` | SQL Server | Named instance | `?instanceName=SQLEXPRESS` | | `authentication` | SQL Server | Auth method: `ntlm`, `azure-active-directory-access-token` | `?authentication=ntlm` | | `domain` | SQL Server | Windows domain (with `authentication=ntlm`) | `?domain=CORP` | + | `sid` | Oracle | Connect by SID instead of service name | `?sid=ORCL` | **SSL/TLS Options:** @@ -245,12 +267,13 @@ This page covers command-line flags and environment variables. For TOML configur | MySQL | ✅ | ✅ | ❌ | ❌ | Certificate verification | | MariaDB | ✅ | ✅ | ❌ | ❌ | Certificate verification | | SQL Server | ✅ | ✅ | ❌ | ❌ | Certificate verification | + | Oracle | ✅ | ✅ | ❌ | ✅ | Plain TCP (`tcps://` only with `require`/`verify-full`) | | SQLite | ❌ | ❌ | ❌ | ❌ | N/A (file-based) | - `sslmode=disable`: All SSL/TLS encryption is turned off. Data is transmitted in plaintext. - `sslmode=require`: Connection is encrypted, but the server's certificate is not verified. - `sslmode=verify-ca`: SSL with CA certificate verification, but no hostname check. **PostgreSQL only.** Use `sslrootcert` to specify the CA certificate path. - - `sslmode=verify-full`: SSL with CA certificate and hostname verification. **PostgreSQL only.** Use `sslrootcert` to specify the CA certificate path. + - `sslmode=verify-full`: SSL with CA certificate and hostname verification. **PostgreSQL and Oracle.** On PostgreSQL use `sslrootcert` to specify the CA certificate path; on Oracle the server certificate is validated against the system trust store. ```bash # Examples @@ -258,6 +281,7 @@ This page covers command-line flags and environment variables. For TOML configur postgres://user:password@localhost:5432/dbname?sslmode=require postgres://user:password@rds-host:5432/dbname?sslmode=verify-ca&sslrootcert=~/.ssl/rds-ca.pem sqlserver://jsmith:secret@localhost:1433/mydb?authentication=ntlm&domain=CORP + oracle://app:secret@db.example.com:2484/PROD?sslmode=verify-full ``` @@ -268,9 +292,9 @@ This page covers command-line flags and environment variables. For TOML configur | Variable | Type | Description | |----------|------|-------------| - | `DB_TYPE` | string | Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite` | + | `DB_TYPE` | string | Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `oracle`, `sqlite` | | `DB_HOST` | string | Database server hostname (not needed for SQLite) | - | `DB_PORT` | number | Database server port. Default: PostgreSQL (`5432`), MySQL/MariaDB (`3306`), SQL Server (`1433`) | + | `DB_PORT` | number | Database server port. Default: PostgreSQL (`5432`), MySQL/MariaDB (`3306`), SQL Server (`1433`), Oracle (`1521`) | | `DB_USER` | string | Database username (not needed for SQLite) | | `DB_PASSWORD` | string | Database password (not needed for SQLite). Supports special characters without URL encoding. | | `DB_NAME` | string | Database name or SQLite file path | diff --git a/docs/config/toml.mdx b/docs/config/toml.mdx index d1a49abe..0e8e7e73 100644 --- a/docs/config/toml.mdx +++ b/docs/config/toml.mdx @@ -219,6 +219,16 @@ Sources define database connections. Each source represents a database that DBHu database = "mydb" user = "admin@tenant.onmicrosoft.com" authentication = "azure-active-directory-access-token" + + # Oracle (database = service name) + [[sources]] + id = "oracle_dev" + type = "oracle" + host = "localhost" + port = 1521 + database = "FREEPDB1" + user = "app" + password = "secret" ``` @@ -269,7 +279,7 @@ Sources define database connections. Each source represents a database that DBHu Connection timeout in seconds. The maximum time to wait when establishing a database connection. - Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server (not applicable to SQLite). + Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle (not applicable to SQLite). ```toml [[sources]] @@ -288,7 +298,7 @@ Sources define database connections. Each source represents a database that DBHu Query timeout in seconds. The maximum time to wait for a query to complete before timing out. - Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server (not applicable to SQLite). + Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle (not applicable to SQLite). ```toml [[sources]] @@ -353,9 +363,9 @@ Sources define database connections. Each source represents a database that DBHu - `disable` - No SSL/TLS encryption. Data is transmitted in plaintext. - `require` - SSL/TLS encryption enabled, but server certificate is not verified. - `verify-ca` - SSL with CA certificate verification (no hostname check). **PostgreSQL only.** - - `verify-full` - SSL with CA certificate and hostname verification. **PostgreSQL only.** + - `verify-full` - SSL with CA certificate and hostname verification. **PostgreSQL and Oracle.** - Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server (not applicable to SQLite). The `verify-ca` and `verify-full` modes are only supported for PostgreSQL. + Supported databases: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle (not applicable to SQLite). `verify-ca` is PostgreSQL only; `verify-full` is supported on PostgreSQL and Oracle (Oracle validates the server certificate against the system trust store, and `sslrootcert` is PostgreSQL only). ```toml # Basic SSL (all network databases) @@ -704,6 +714,7 @@ Tools define MCP tools (like `execute_sql`) with specific execution settings. To | MariaDB | `?`, `?`, `?` | `WHERE id = ? AND status = ?` | | SQLite | `?`, `?`, `?` | `WHERE id = ? AND status = ?` | | SQL Server | `@p1`, `@p2`, `@p3` | `WHERE id = @p1 AND status = @p2` | + | Oracle | `:1`, `:2`, `:3` | `WHERE id = :1 AND status = :2` | The number of parameters must match the number of placeholders in your SQL statement. Validation occurs at server startup. diff --git a/docs/index.mdx b/docs/index.mdx index 8a56c39a..1ad62557 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -17,17 +17,17 @@ DBHub is a minimal MCP server: token-efficient, zero-dependency, and just two to ``` +------------------+ +--------------+ +------------------+ | | | | | | - | | | | | | | Claude Desktop +--->+ +--->+ PostgreSQL | | | | | | | | Claude Code +--->+ +--->+ SQL Server | | | | | | | - | Cursor +--->+ DBHub +--->+ SQLite | + | Cursor +--->+ DBHub +--->+ Oracle | | | | | | | - | VS Code +--->+ +--->+ MySQL | + | VS Code +--->+ +--->+ SQLite | | | | | | | - | Other Clients +--->+ +--->+ MariaDB | + | Other Clients +--->+ +--->+ MySQL | | | | | | | + | | | +--->+ MariaDB | | | | | | | +------------------+ +--------------+ +------------------+ MCP Clients MCP Server Databases @@ -54,14 +54,14 @@ DBHub loads just 2 tools by default at **1.4k tokens** — 13-14x fewer than alt ## Supported Databases -PostgreSQL, MySQL, SQL Server, MariaDB, and SQLite. +PostgreSQL, MySQL, SQL Server, MariaDB, Oracle, and SQLite. ## Why DBHub? DBHub brings powerful database capabilities to AI coding assistants: - **Minimal**: Zero dependency, token efficient with a minimal set of MCP tools to maximize context window -- **Multi-Database**: PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite through a single interface +- **Multi-Database**: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, and SQLite through a single interface - **Multi-Connection**: Connect to multiple databases simultaneously with TOML configuration - **Guardrails**: Read-only mode, row limiting, and query timeout to prevent runaway operations - **Secure Access**: SSH tunneling and SSL/TLS encryption @@ -112,7 +112,7 @@ flowchart TB end %% Databases - Databases["PostgreSQL, MySQL, SQL Server, MariaDB, SQLite"] + Databases["PostgreSQL, MySQL, SQL Server, MariaDB, Oracle, SQLite"] %% Connections User --> WB diff --git a/docs/installation.mdx b/docs/installation.mdx index 94aabbee..b27b1c08 100644 --- a/docs/installation.mdx +++ b/docs/installation.mdx @@ -38,7 +38,7 @@ The npm method requires **Node.js >= 22.5.0** (DBHub uses Node's built-in `node: ### Minimal Installation -By default, DBHub attempts to install drivers for all supported databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite). If you only need specific databases, you can skip the unnecessary drivers to reduce installation size. +By default, DBHub attempts to install drivers for all supported databases (PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite). If you only need specific databases, you can skip the unnecessary drivers to reduce installation size. This applies to `npm install` (global or local). When using `npx`, npm will attempt to install all optional dependencies, but some drivers may be skipped if their installation fails, a required transitive dependency is missing, or the platform is not supported. @@ -55,6 +55,7 @@ Available driver packages: - `mysql2` — MySQL - `mariadb` — MariaDB - `mssql` — SQL Server +- `oracledb` — Oracle (Thin mode: pure JavaScript, no Oracle Instant Client required) SQLite uses the built-in `node:sqlite` module (Node.js 22.5+), so it requires no driver package or native compilation and is always available. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 29387064..597c242e 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -155,5 +155,5 @@ The skill guides the AI to follow the **explore-then-query** pattern: discover s Once you've verified DBHub works in demo mode, connect it to your actual database. - Complete connection string formats and options for PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite. + Complete connection string formats and options for PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, and SQLite. \ No newline at end of file diff --git a/docs/tools/custom-tools.mdx b/docs/tools/custom-tools.mdx index af5e4d9f..32127004 100644 --- a/docs/tools/custom-tools.mdx +++ b/docs/tools/custom-tools.mdx @@ -141,6 +141,21 @@ The same tool pattern works across different databases, just adjust the paramete description = "Product ID" ``` + + + ```toml + [[tools]] + name = "get_product" + description = "Get product by ID" + source = "oracle_db" + statement = "SELECT * FROM products WHERE id = :1" + + [[tools.parameters]] + name = "product_id" + type = "integer" + description = "Product ID" + ``` + See [Parameter Placeholders](/config/toml#parameters) for syntax reference. diff --git a/docs/tools/explain-sql.mdx b/docs/tools/explain-sql.mdx index 152f2c14..dc8f7372 100644 --- a/docs/tools/explain-sql.mdx +++ b/docs/tools/explain-sql.mdx @@ -7,7 +7,7 @@ Show the execution plan for a SQL statement without running it. ## Features - **Never executes**: Only ever compiles/plans the statement — safe to enable regardless of the source's `readonly` setting -- **Per-dialect output**: Uses `EXPLAIN` on PostgreSQL, MySQL, MariaDB, and SQL Server, and `EXPLAIN QUERY PLAN` on SQLite (bare `EXPLAIN` on SQLite returns low-level bytecode, not a readable plan) +- **Per-dialect output**: Uses `EXPLAIN` on PostgreSQL, MySQL, MariaDB, and SQL Server, `EXPLAIN PLAN` + `DBMS_XPLAN` on Oracle, and `EXPLAIN QUERY PLAN` on SQLite (bare `EXPLAIN` on SQLite returns low-level bytecode, not a readable plan) - **Opt-in only**: Not part of the default tool pair — must be explicitly enabled per source diff --git a/docs/tools/health-check.mdx b/docs/tools/health-check.mdx index 22623403..e37de8b2 100644 --- a/docs/tools/health-check.mdx +++ b/docs/tools/health-check.mdx @@ -8,7 +8,7 @@ Report operational health metrics for a database source: connection pool state a - **Connection pool state**: Total/active/idle session counts, idle-in-transaction sessions, the configured connection ceiling, and how long the longest-running query or idle-in-transaction session has been open - **Buffer cache hit ratio**: Percentage of reads served from cache vs disk, useful for spotting an undersized cache before it becomes a production incident -- **Per-engine support**: Implemented for PostgreSQL, MySQL, MariaDB, and SQL Server. SQLite has no connection pool or cache-hit concept to report, so `health_check` returns an `UNSUPPORTED` error there +- **Per-engine support**: Implemented for PostgreSQL, MySQL, MariaDB, and SQL Server. SQLite has no connection pool or cache-hit concept to report, and Oracle is not implemented yet, so `health_check` returns an `UNSUPPORTED` error there - **Graceful degradation**: On MySQL/MariaDB/SQL Server, some metrics require an elevated privilege the connected user may not have. Rather than failing outright, `health_check` returns whatever it can and adds a `notes` entry explaining what's missing - **Opt-in only**: Not part of the default tool pair — must be explicitly enabled per source diff --git a/docs/tools/search-objects.mdx b/docs/tools/search-objects.mdx index 7cb77962..e47d46b7 100644 --- a/docs/tools/search-objects.mdx +++ b/docs/tools/search-objects.mdx @@ -173,6 +173,7 @@ When using `detail_level: "summary"` or `"full"`, the tool includes database com | MySQL | `ALTER TABLE ... COMMENT` | `ALTER TABLE ... MODIFY COLUMN ... COMMENT` | | MariaDB | `ALTER TABLE ... COMMENT` | `ALTER TABLE ... MODIFY COLUMN ... COMMENT` | | SQL Server | `sp_addextendedproperty` (MS_Description) | `sp_addextendedproperty` (MS_Description) | +| Oracle | `COMMENT ON TABLE` | `COMMENT ON COLUMN` | | SQLite | Not supported | Not supported | ## Usage Patterns diff --git a/package.json b/package.json index f8bb617b..07258d5b 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "dbhub", "version": "1.2.5", "mcpName": "io.github.bytebase/dbhub", - "description": "Minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, SQLite, MariaDB", + "description": "Minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, Oracle, SQLite, MariaDB", "repository": { "type": "git", "url": "https://github.com/bytebase/dbhub.git" diff --git a/server.json b/server.json index 0bc93c25..96e7c6cf 100644 --- a/server.json +++ b/server.json @@ -2,7 +2,7 @@ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.bytebase/dbhub", "title": "DBHub", - "description": "Minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, SQLite, MariaDB", + "description": "Minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, Oracle, SQLite, MariaDB", "repository": { "url": "https://github.com/bytebase/dbhub", "source": "github" @@ -26,7 +26,7 @@ }, { "name": "DB_TYPE", - "description": "Database type: postgres, mysql, mariadb, sqlserver, sqlite", + "description": "Database type: postgres, mysql, mariadb, sqlserver, oracle, sqlite", "isRequired": false, "format": "string", "isSecret": false