@bytebase/dbhub 0.9.0 → 0.11.0

package/README.md

@@ -22,12 +22,15 @@ DBHub is a universal database gateway implementing the Model Context Protocol (M
  |                  |    |              |    |                  |
  |  Claude Desktop  +--->+              +--->+    PostgreSQL    |
  |                  |    |              |    |                  |
- |  Cursor          +--->+    DBHub     +--->+    SQL Server    |
+ |  Claude Code     +--->+              +--->+    SQL Server    |
  |                  |    |              |    |                  |
- |                  |    |              +--->+    MySQL         |
+ |  Cursor          +--->+    DBHub     +--->+    SQLite        |
+ |                  |    |              |    |                  |
+ |  Other Clients   +--->+              +--->+    MySQL         |
  |                  |    |              |    |                  |
  |                  |    |              +--->+    MariaDB       |
  |                  |    |              |    |                  |
+ |                  |    |              |    |                  |
  +------------------+    +--------------+    +------------------+
       MCP Clients           MCP Server             Databases
 ```
@@ -42,27 +45,27 @@ https://demo.dbhub.ai/message connects a [sample employee database](https://gith
 
 ### Database Resources
 
-| Resource Name               | URI Format                                             | PostgreSQL | MySQL | MariaDB | SQL Server |
-| --------------------------- | ------------------------------------------------------ | :--------: | :---: | :-----: | :--------: |
-| schemas                     | `db://schemas`                                         |     ✅     |  ✅   |   ✅    |     ✅     |
-| tables_in_schema            | `db://schemas/{schemaName}/tables`                     |     ✅     |  ✅   |   ✅    |     ✅     |
-| table_structure_in_schema   | `db://schemas/{schemaName}/tables/{tableName}`         |     ✅     |  ✅   |   ✅    |     ✅     |
-| indexes_in_table            | `db://schemas/{schemaName}/tables/{tableName}/indexes` |     ✅     |  ✅   |   ✅    |     ✅     |
-| procedures_in_schema        | `db://schemas/{schemaName}/procedures`                 |     ✅     |  ✅   |   ✅    |     ✅     |
-| procedure_details_in_schema | `db://schemas/{schemaName}/procedures/{procedureName}` |     ✅     |  ✅   |   ✅    |     ✅     |
+| Resource Name               | URI Format                                             | PostgreSQL | MySQL | MariaDB | SQL Server | SQLite |
+| --------------------------- | ------------------------------------------------------ | :--------: | :---: | :-----: | :--------: | :----: |
+| schemas                     | `db://schemas`                                         |     ✅     |  ✅   |   ✅    |     ✅     |   ✅   |
+| tables_in_schema            | `db://schemas/{schemaName}/tables`                     |     ✅     |  ✅   |   ✅    |     ✅     |   ✅   |
+| table_structure_in_schema   | `db://schemas/{schemaName}/tables/{tableName}`         |     ✅     |  ✅   |   ✅    |     ✅     |   ✅   |
+| indexes_in_table            | `db://schemas/{schemaName}/tables/{tableName}/indexes` |     ✅     |  ✅   |   ✅    |     ✅     |   ✅   |
+| procedures_in_schema        | `db://schemas/{schemaName}/procedures`                 |     ✅     |  ✅   |   ✅    |     ✅     |   ❌   |
+| procedure_details_in_schema | `db://schemas/{schemaName}/procedures/{procedureName}` |     ✅     |  ✅   |   ✅    |     ✅     |   ❌   |
 
 ### Database Tools
 
-| Tool        | Command Name  | Description                                                         | PostgreSQL | MySQL | MariaDB | SQL Server |
-| ----------- | ------------- | ------------------------------------------------------------------- | :--------: | :---: | :-----: | :--------: |
-| Execute SQL | `execute_sql` | Execute single or multiple SQL statements (separated by semicolons) |     ✅     |  ✅   |   ✅    |     ✅     |
+| Tool        | Command Name  | Description                                                         | PostgreSQL | MySQL | MariaDB | SQL Server | SQLite |
+| ----------- | ------------- | ------------------------------------------------------------------- | :--------: | :---: | :-----: | :--------: | ------ |
+| Execute SQL | `execute_sql` | Execute single or multiple SQL statements (separated by semicolons) |     ✅     |  ✅   |   ✅    |     ✅     | ✅     |
 
 ### Prompt Capabilities
 
-| Prompt              | Command Name   | PostgreSQL | MySQL | MariaDB | SQL Server |
-| ------------------- | -------------- | :--------: | :---: | :-----: | :--------: |
-| Generate SQL        | `generate_sql` |     ✅     |  ✅   |   ✅    |     ✅     |
-| Explain DB Elements | `explain_db`   |     ✅     |  ✅   |   ✅    |     ✅     |
+| Prompt              | Command Name   | PostgreSQL | MySQL | MariaDB | SQL Server | SQLite |
+| ------------------- | -------------- | :--------: | :---: | :-----: | :--------: | ------ |
+| Generate SQL        | `generate_sql` |     ✅     |  ✅   |   ✅    |     ✅     | ✅     |
+| Explain DB Elements | `explain_db`   |     ✅     |  ✅   |   ✅    |     ✅     | ✅     |
 
 ## Installation
 
@@ -79,15 +82,33 @@ docker run --rm --init \
    --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
 ```
 
-
+```bash
+# Demo mode with sqlite sample employee database
+docker run --rm --init \
+   --name dbhub \
+   --publish 8080:8080 \
+   bytebase/dbhub \
+   --transport http \
+   --port 8080 \
+   --demo
+```
 
 ### NPM
 
 ```bash
 # PostgreSQL example
 npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
+
+# Demo mode with sqlite sample employee database
+npx @bytebase/dbhub --transport http --port 8080 --demo
+```
+
+```bash
+# Demo mode with sample employee database
+npx @bytebase/dbhub --transport http --port 8080 --demo
 ```
 
+> Note: The demo mode includes a bundled SQLite sample "employee" database with tables for employees, departments, salaries, and more.
 
 ### Claude Desktop
 
@@ -124,10 +145,18 @@ npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password
         "postgres://user:password@localhost:5432/dbname?sslmode=disable"
       ]
     },
+    "dbhub-demo": {
+      "command": "npx",
+      "args": ["-y", "@bytebase/dbhub", "--transport", "stdio", "--demo"]
+    }
   }
 }
 ```
 
+### Claude Code
+
+Check https://docs.anthropic.com/en/docs/claude-code/mcp
+
 ### Cursor
 
 [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=dbhub&config=eyJjb21tYW5kIjoibnB4IEBieXRlYmFzZS9kYmh1YiIsImVudiI6eyJUUkFOU1BPUlQiOiJzdGRpbyIsIkRTTiI6InBvc3RncmVzOi8vdXNlcjpwYXNzd29yZEBsb2NhbGhvc3Q6NTQzMi9kYm5hbWU%2Fc3NsbW9kZT1kaXNhYmxlIiwiUkVBRE9OTFkiOiJ0cnVlIn19)
@@ -139,16 +168,30 @@ npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password
 
 ## Usage
 
+### Read-only Mode
+
+You can run DBHub in read-only mode, which restricts SQL query execution to read-only operations:
+
+```bash
+# Enable read-only mode
+npx @bytebase/dbhub --readonly --dsn "postgres://user:password@localhost:5432/dbname"
+```
+
+In read-only mode, only [readonly SQL operations](https://github.com/bytebase/dbhub/blob/main/src/utils/allowed-keywords.ts) are allowed.
+
+This provides an additional layer of security when connecting to production databases.
+
 ### SSL Connections
 
 You can specify the SSL mode using the `sslmode` parameter in your DSN string:
 
-| Database   | `sslmode=disable` | `sslmode=require` |      Default SSL Behavior      |
-| ---------- | :---------------: | :---------------: | :----------------------------: |
-| PostgreSQL |        ✅         |        ✅         |    Certificate verification    |
-| MySQL      |        ✅         |        ✅         |    Certificate verification    |
-| MariaDB    |        ✅         |        ✅         |    Certificate verification    |
-| SQL Server |        ✅         |        ✅         |    Certificate verification    |
+| Database   | `sslmode=disable` | `sslmode=require` |   Default SSL Behavior   |
+| ---------- | :---------------: | :---------------: | :----------------------: |
+| PostgreSQL |        ✅         |        ✅         | Certificate verification |
+| MySQL      |        ✅         |        ✅         | Certificate verification |
+| MariaDB    |        ✅         |        ✅         | Certificate verification |
+| SQL Server |        ✅         |        ✅         | Certificate verification |
+| SQLite     |        ❌         |        ❌         |     N/A (file-based)     |
 
 **SSL Mode Options:**
 
@@ -170,21 +213,61 @@ postgres://user:password@localhost:5432/dbname?sslmode=require
 postgres://user:password@localhost:5432/dbname
 ```
 
-### Read-only Mode
+### SSH Tunnel Support
 
-You can run DBHub in read-only mode, which restricts SQL query execution to read-only operations:
+DBHub supports connecting to databases through SSH tunnels, enabling secure access to databases in private networks or behind firewalls.
+
+#### SSH with Password Authentication
 
 ```bash
-# Enable read-only mode
-npx @bytebase/dbhub --readonly --dsn "postgres://user:password@localhost:5432/dbname"
+npx @bytebase/dbhub \
+  --dsn "postgres://dbuser:dbpass@database.internal:5432/mydb" \
+  --ssh-host bastion.example.com \
+  --ssh-user ubuntu \
+  --ssh-password mypassword
 ```
 
-In read-only mode, only [readonly SQL operations](https://github.com/bytebase/dbhub/blob/main/src/utils/allowed-keywords.ts) are allowed.
+#### SSH with Private Key Authentication
 
-This provides an additional layer of security when connecting to production databases.
+```bash
+npx @bytebase/dbhub \
+  --dsn "postgres://dbuser:dbpass@database.internal:5432/mydb" \
+  --ssh-host bastion.example.com \
+  --ssh-user ubuntu \
+  --ssh-key ~/.ssh/id_rsa
+```
+
+#### SSH with Private Key and Passphrase
+
+```bash
+npx @bytebase/dbhub \
+  --dsn "postgres://dbuser:dbpass@database.internal:5432/mydb" \
+  --ssh-host bastion.example.com \
+  --ssh-port 2222 \
+  --ssh-user ubuntu \
+  --ssh-key ~/.ssh/id_rsa \
+  --ssh-passphrase mykeypassphrase
+```
+
+#### Using Environment Variables
+
+```bash
+export SSH_HOST=bastion.example.com
+export SSH_USER=ubuntu
+export SSH_KEY=~/.ssh/id_rsa
+npx @bytebase/dbhub --dsn "postgres://dbuser:dbpass@database.internal:5432/mydb"
+```
+
+**Note**: When using SSH tunnels, the database host in your DSN should be the hostname/IP as seen from the SSH server (bastion host), not from your local machine.
 
 ### Configure your database connection
 
+You can use DBHub in demo mode with a sample employee database for testing:
+
+```bash
+npx @bytebase/dbhub  --demo
+```
+
 > [!WARNING]
 > If your user/password contains special characters, you need to escape them first. (e.g. `pass#word` should be escaped as `pass%23word`)
 
@@ -215,13 +298,13 @@ For real databases, a Database Source Name (DSN) is required. You can provide th
 
 DBHub supports the following database connection string formats:
 
-| Database   | DSN Format                                                | Example                                                                                                        |
-| ---------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| MySQL      | `mysql://[user]:[password]@[host]:[port]/[database]`      | `mysql://user:password@localhost:3306/dbname?sslmode=disable`                                                  |
-| MariaDB    | `mariadb://[user]:[password]@[host]:[port]/[database]`    | `mariadb://user:password@localhost:3306/dbname?sslmode=disable`                                                |
-| PostgreSQL | `postgres://[user]:[password]@[host]:[port]/[database]`   | `postgres://user:password@localhost:5432/dbname?sslmode=disable`                                               |
-| SQL Server | `sqlserver://[user]:[password]@[host]:[port]/[database]`  | `sqlserver://user:password@localhost:1433/dbname?sslmode=disable`                                              |
-
+| Database   | DSN Format                                               | Example                                                                                                        |
+| ---------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| MySQL      | `mysql://[user]:[password]@[host]:[port]/[database]`     | `mysql://user:password@localhost:3306/dbname?sslmode=disable`                                                  |
+| MariaDB    | `mariadb://[user]:[password]@[host]:[port]/[database]`   | `mariadb://user:password@localhost:3306/dbname?sslmode=disable`                                                |
+| PostgreSQL | `postgres://[user]:[password]@[host]:[port]/[database]`  | `postgres://user:password@localhost:5432/dbname?sslmode=disable`                                               |
+| SQL Server | `sqlserver://[user]:[password]@[host]:[port]/[database]` | `sqlserver://user:password@localhost:1433/dbname?sslmode=disable`                                              |
+| SQLite     | `sqlite:///[path/to/file]` or `sqlite:///:memory:`       | `sqlite:///path/to/database.db`, `sqlite:C:/Users/YourName/data/database.db (windows)` or `sqlite:///:memory:` |
 
 #### SQL Server
 
@@ -246,13 +329,21 @@ Extra query parameters:
 
 ### Command line options
 
-| Option    | Environment Variable | Description                                                      | Default  |
-| --------- | -------------------- | ---------------------------------------------------------------- | -------- |
-| dsn       | `DSN`                | Database connection string                                       | Required |
-| transport | `TRANSPORT`          | Transport mode: `stdio` or `http`                                | `stdio`  |
-| port      | `PORT`               | HTTP server port (only applicable when using `--transport=http`) | `8080`   |
-| readonly  | `READONLY`           | Restrict SQL execution to read-only operations                   | `false`  |
-
+| Option         | Environment Variable | Description                                                      | Default                      |
+| -------------- | -------------------- | ---------------------------------------------------------------- | ---------------------------- |
+| dsn            | `DSN`                | Database connection string                                       | Required if not in demo mode |
+| transport      | `TRANSPORT`          | Transport mode: `stdio` or `http`                                | `stdio`                      |
+| port           | `PORT`               | HTTP server port (only applicable when using `--transport=http`) | `8080`                       |
+| readonly       | `READONLY`           | Restrict SQL execution to read-only operations                   | `false`                      |
+| demo           | N/A                  | Run in demo mode with sample employee database                   | `false`                      |
+| ssh-host       | `SSH_HOST`           | SSH server hostname for tunnel connection                        | N/A                          |
+| ssh-port       | `SSH_PORT`           | SSH server port                                                  | `22`                         |
+| ssh-user       | `SSH_USER`           | SSH username                                                     | N/A                          |
+| ssh-password   | `SSH_PASSWORD`       | SSH password (for password authentication)                       | N/A                          |
+| ssh-key        | `SSH_KEY`            | Path to SSH private key file                                     | N/A                          |
+| ssh-passphrase | `SSH_PASSPHRASE`     | Passphrase for SSH private key                                   | N/A                          |
+
+The demo mode uses an in-memory SQLite database loaded with the [sample employee database](https://github.com/bytebase/dbhub/tree/main/resources/employee-sqlite) that includes tables for employees, departments, titles, salaries, department employees, and department managers. The sample database includes SQL scripts for table creation, data loading, and testing.
 
 ## Development
 
@@ -310,6 +401,8 @@ pnpm test src/connectors/__tests__/mysql.integration.test.ts
 pnpm test src/connectors/__tests__/mariadb.integration.test.ts
 # Run only SQL Server integration tests
 pnpm test src/connectors/__tests__/sqlserver.integration.test.ts
+# Run only SQLite integration tests
+pnpm test src/connectors/__tests__/sqlite.integration.test.ts
 # Run JSON RPC integration tests
 pnpm test src/__tests__/json-rpc-integration.test.ts
 ```
@@ -345,7 +438,6 @@ docker pull mcr.microsoft.com/mssql/server:2019-latest
 - Ensure Docker has sufficient memory allocated (4GB+ recommended)
 - Consider running SQL Server tests separately if experiencing timeouts
 
-
 **Network/Resource Issues:**
 
 ```bash