@bytebase/dbhub 0.11.3 → 0.11.5

package/README.md

@@ -43,12 +43,6 @@ DBHub is a universal database gateway implementing the Model Context Protocol (M
       MCP Clients           MCP Server             Databases
 ```
 
-## Demo HTTP Endpoint
-
-https://demo.dbhub.ai/message connects a [sample employee database](https://github.com/bytebase/employee-sample-database). You can point Cursor or MCP Inspector to it to see it in action.
-
-![mcp-inspector](https://raw.githubusercontent.com/bytebase/dbhub/main/resources/images/mcp-inspector.webp)
-
 ## Supported Matrix
 
 ### Database Resources
@@ -101,6 +95,29 @@ docker run --rm --init \
    --demo
 ```
 
+**Docker Compose Setup:**
+
+If you're using Docker Compose for development, add DBHub to your `docker-compose.yml`:
+
+```yaml
+dbhub:
+  image: bytebase/dbhub:latest
+  container_name: dbhub
+  ports:
+    - "8080:8080"
+  environment:
+    - DBHUB_LOG_LEVEL=info
+  command:
+    - --transport
+    - http
+    - --port
+    - "8080"
+    - --dsn
+    - "postgres://user:password@database:5432/dbname"
+  depends_on:
+    - database
+```
+
 ### NPM
 
 ```bash
@@ -181,6 +198,74 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=dbhub&config=eyJjb21tYW5kIjo
 - Cursor supports both `stdio` and `http`.
 - Follow [Cursor MCP guide](https://docs.cursor.com/context/model-context-protocol) and make sure to use [Agent](https://docs.cursor.com/chat/agent) mode.
 
+### VSCode + Copilot
+
+Check https://code.visualstudio.com/docs/copilot/customization/mcp-servers
+
+VSCode with GitHub Copilot can connect to DBHub via both `stdio` and `http` transports. This enables AI agents to interact with your development database through a secure interface.
+
+- VSCode supports both `stdio` and `http` transports
+- Configure MCP server in `.vscode/mcp.json`:
+
+**Stdio Transport:**
+
+```json
+{
+  "servers": {
+    "dbhub": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@bytebase/dbhub",
+        "--transport",
+        "stdio",
+        "--dsn",
+        "postgres://user:password@localhost:5432/dbname"
+      ]
+    }
+  },
+  "inputs": []
+}
+```
+
+**HTTP Transport:**
+
+```json
+{
+  "servers": {
+    "dbhub": {
+      "url": "http://localhost:8080/message",
+      "type": "http"
+    }
+  },
+  "inputs": []
+}
+```
+
+**Copilot Instructions:**
+
+You can provide Copilot with context by creating `.github/copilot-instructions.md`:
+
+```markdown
+## Database Access
+
+This project provides an MCP server (DBHub) for secure SQL access to the development database.
+
+AI agents can execute SQL queries. In read-only mode (recommended for production):
+
+- `SELECT * FROM users LIMIT 5;`
+- `SHOW TABLES;`
+- `DESCRIBE table_name;`
+
+In read-write mode (development/testing):
+
+- `INSERT INTO users (name, email) VALUES ('John', 'john@example.com');`
+- `UPDATE users SET status = 'active' WHERE id = 1;`
+- `CREATE TABLE test_table (id INT PRIMARY KEY);`
+
+Use `--readonly` flag to restrict to read-only operations for safety.
+```
+
 ## Usage
 
 ### Read-only Mode
@@ -196,6 +281,40 @@ In read-only mode, only [readonly SQL operations](https://github.com/bytebase/db
 
 This provides an additional layer of security when connecting to production databases.
 
+### Suffix Tool Names with ID
+
+You can suffix tool names with a custom ID using the `--id` flag or `ID` environment variable. This is useful when running multiple DBHub instances (e.g., in Cursor) to allow the client to route queries to the correct database.
+
+**Example configuration for multiple databases in Cursor:**
+
+```json
+{
+  "mcpServers": {
+    "dbhub-prod": {
+      "command": "npx",
+      "args": ["-y", "@bytebase/dbhub"],
+      "env": {
+        "ID": "prod",
+        "DSN": "postgres://user:password@prod-host:5432/dbname"
+      }
+    },
+    "dbhub-staging": {
+      "command": "npx",
+      "args": ["-y", "@bytebase/dbhub"],
+      "env": {
+        "ID": "staging",
+        "DSN": "mysql://user:password@staging-host:3306/dbname"
+      }
+    }
+  }
+}
+```
+
+With this configuration:
+
+- Production database tools: `execute_sql_prod`
+- Staging database tools: `execute_sql_staging`
+
 ### Row Limiting
 
 You can limit the number of rows returned from SELECT queries using the `--max-rows` parameter. This helps prevent accidentally retrieving too much data from large tables:
@@ -314,9 +433,14 @@ 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`)
+> If your user/password contains special characters, you have two options:
+>
+> 1. Escape them in the DSN (e.g. `pass#word` should be escaped as `pass%23word`)
+> 2. Use the individual database parameters method below (recommended)
+
+For real databases, you can configure the database connection in two ways:
 
-For real databases, a Database Source Name (DSN) is required. You can provide this in several ways:
+#### Method 1: Database Source Name (DSN)
 
 - **Command line argument** (highest priority):
 
@@ -338,6 +462,45 @@ For real databases, a Database Source Name (DSN) is required. You can provide th
   DSN=postgres://user:password@localhost:5432/dbname?sslmode=disable
   ```
 
+#### Method 2: Individual Database Parameters
+
+If your password contains special characters that would break URL parsing, use individual environment variables instead:
+
+- **Environment variables**:
+
+  ```bash
+  export DB_TYPE=postgres
+  export DB_HOST=localhost
+  export DB_PORT=5432
+  export DB_USER=myuser
+  export DB_PASSWORD='my@complex:password/with#special&chars'
+  export DB_NAME=mydatabase
+  npx @bytebase/dbhub
+  ```
+
+- **Environment file**:
+  ```
+  DB_TYPE=postgres
+  DB_HOST=localhost
+  DB_PORT=5432
+  DB_USER=myuser
+  DB_PASSWORD=my@complex:password/with#special&chars
+  DB_NAME=mydatabase
+  ```
+
+**Supported DB_TYPE values**: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite`
+
+**Default ports** (when DB_PORT is omitted):
+
+- PostgreSQL: `5432`
+- MySQL/MariaDB: `3306`
+- SQL Server: `1433`
+
+**For SQLite**: Only `DB_TYPE=sqlite` and `DB_NAME=/path/to/database.db` are required.
+
+> [!TIP]
+> Use the individual parameter method when your password contains special characters like `@`, `:`, `/`, `#`, `&`, `=` that would break DSN parsing.
+
 > [!WARNING]
 > When running in Docker, use `host.docker.internal` instead of `localhost` to connect to databases running on your host machine. For example: `mysql://user:password@host.docker.internal:3306/dbname`
 
@@ -374,20 +537,27 @@ Extra query parameters:
 
 ### Command line options
 
-| 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`                      |
-| max-rows       | N/A                  | Limit the number of rows returned from SELECT queries            | No limit                     |
-| 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                          |
+| Option         | Environment Variable | Description                                                           | Default                      |
+| -------------- | -------------------- | --------------------------------------------------------------------- | ---------------------------- |
+| dsn            | `DSN`                | Database connection string                                            | Required if not in demo mode |
+| N/A            | `DB_TYPE`            | Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite`  | N/A                          |
+| N/A            | `DB_HOST`            | Database server hostname (not needed for SQLite)                      | N/A                          |
+| N/A            | `DB_PORT`            | Database server port (uses default if omitted, not needed for SQLite) | N/A                          |
+| N/A            | `DB_USER`            | Database username (not needed for SQLite)                             | N/A                          |
+| N/A            | `DB_PASSWORD`        | Database password (not needed for SQLite)                             | N/A                          |
+| N/A            | `DB_NAME`            | Database name or SQLite file path                                     | N/A                          |
+| 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`                      |
+| max-rows       | N/A                  | Limit the number of rows returned from SELECT queries                 | No limit                     |
+| demo           | N/A                  | Run in demo mode with sample employee database                        | `false`                      |
+| id             | `ID`                 | Instance identifier to suffix tool names (for multi-instance)         | N/A                          |
+| 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.
 
@@ -511,6 +681,8 @@ The project includes pre-commit hooks to run tests automatically before each com
 
 ### Debug with [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
 
+![mcp-inspector](https://raw.githubusercontent.com/bytebase/dbhub/main/resources/images/mcp-inspector.webp)
+
 #### stdio
 
 ```bash

package/dist/index.js

@@ -1046,10 +1046,19 @@ var SQLiteConnector = class {
   async disconnect() {
     if (this.db) {
       try {
-        this.db.close();
+        if (!this.db.inTransaction) {
+          this.db.close();
+        } else {
+          try {
+            this.db.exec("ROLLBACK");
+          } catch (rollbackError) {
+          }
+          this.db.close();
+        }
         this.db = null;
       } catch (error) {
-        throw error;
+        console.error("Error during SQLite disconnect:", error);
+        this.db = null;
       }
     }
     return Promise.resolve();
@@ -2310,6 +2319,62 @@ function isReadOnlyMode() {
   }
   return false;
 }
+function buildDSNFromEnvParams() {
+  const dbType = process.env.DB_TYPE;
+  const dbHost = process.env.DB_HOST;
+  const dbUser = process.env.DB_USER;
+  const dbPassword = process.env.DB_PASSWORD;
+  const dbName = process.env.DB_NAME;
+  const dbPort = process.env.DB_PORT;
+  if (dbType?.toLowerCase() === "sqlite") {
+    if (!dbName) {
+      return null;
+    }
+  } else {
+    if (!dbType || !dbHost || !dbUser || !dbPassword || !dbName) {
+      return null;
+    }
+  }
+  const supportedTypes = ["postgres", "postgresql", "mysql", "mariadb", "sqlserver", "sqlite"];
+  if (!supportedTypes.includes(dbType.toLowerCase())) {
+    throw new Error(`Unsupported DB_TYPE: ${dbType}. Supported types: ${supportedTypes.join(", ")}`);
+  }
+  let port = dbPort;
+  if (!port) {
+    switch (dbType.toLowerCase()) {
+      case "postgres":
+      case "postgresql":
+        port = "5432";
+        break;
+      case "mysql":
+      case "mariadb":
+        port = "3306";
+        break;
+      case "sqlserver":
+        port = "1433";
+        break;
+      case "sqlite":
+        return {
+          dsn: `sqlite:///${dbName}`,
+          source: "individual environment variables"
+        };
+      default:
+        throw new Error(`Unknown database type for port determination: ${dbType}`);
+    }
+  }
+  const user = dbUser;
+  const password = dbPassword;
+  const dbNameStr = dbName;
+  const encodedUser = encodeURIComponent(user);
+  const encodedPassword = encodeURIComponent(password);
+  const encodedDbName = encodeURIComponent(dbNameStr);
+  const protocol = dbType.toLowerCase() === "postgresql" ? "postgres" : dbType.toLowerCase();
+  const dsn = `${protocol}://${encodedUser}:${encodedPassword}@${dbHost}:${port}/${encodedDbName}`;
+  return {
+    dsn,
+    source: "individual environment variables"
+  };
+}
 function resolveDSN() {
   const args = parseCommandLineArgs();
   if (isDemoMode()) {
@@ -2325,10 +2390,23 @@ function resolveDSN() {
   if (process.env.DSN) {
     return { dsn: process.env.DSN, source: "environment variable" };
   }
+  const envParamsResult = buildDSNFromEnvParams();
+  if (envParamsResult) {
+    return envParamsResult;
+  }
   const loadedEnvFile = loadEnvFiles();
   if (loadedEnvFile && process.env.DSN) {
     return { dsn: process.env.DSN, source: `${loadedEnvFile} file` };
   }
+  if (loadedEnvFile) {
+    const envFileParamsResult = buildDSNFromEnvParams();
+    if (envFileParamsResult) {
+      return {
+        dsn: envFileParamsResult.dsn,
+        source: `${loadedEnvFile} file (individual parameters)`
+      };
+    }
+  }
   return null;
 }
 function resolveTransport() {
@@ -2377,6 +2455,16 @@ function redactDSN(dsn) {
     return dsn.replace(/\/\/([^:]+):([^@]+)@/, "//$1:***@");
   }
 }
+function resolveId() {
+  const args = parseCommandLineArgs();
+  if (args.id) {
+    return { id: args.id, source: "command line argument" };
+  }
+  if (process.env.ID) {
+    return { id: process.env.ID, source: "environment variable" };
+  }
+  return null;
+}
 function resolveSSHConfig() {
   const args = parseCommandLineArgs();
   const hasSSHArgs = args["ssh-host"] || process.env.SSH_HOST;
@@ -3051,9 +3139,10 @@ async function executeSqlToolHandler({ sql: sql2 }, _extra) {
 }
 
 // src/tools/index.ts
-function registerTools(server) {
+function registerTools(server, id) {
+  const toolName = id ? `execute_sql_${id}` : "execute_sql";
   server.tool(
-    "execute_sql",
+    toolName,
     "Execute a SQL query on the current database",
     executeSqlSchema,
     executeSqlToolHandler
@@ -3497,10 +3586,12 @@ v${version}${modeText} - Universal Database MCP Server
 }
 async function main() {
   try {
+    const idData = resolveId();
+    const id = idData?.id;
     const dsnData = resolveDSN();
     if (!dsnData) {
       const samples = ConnectorRegistry.getAllSampleDSNs();
-      const sampleFormats = Object.entries(samples).map(([id, dsn]) => `  - ${id}: ${dsn}`).join("\n");
+      const sampleFormats = Object.entries(samples).map(([id2, dsn]) => `  - ${id2}: ${dsn}`).join("\n");
       console.error(`
 ERROR: Database connection string (DSN) is required.
 Please provide the DSN in one of these ways (in order of priority):
@@ -3523,13 +3614,16 @@ See documentation for more details on configuring database connections.
         version: SERVER_VERSION
       });
       registerResources(server);
-      registerTools(server);
+      registerTools(server, id);
       registerPrompts(server);
       return server;
     };
     const connectorManager = new ConnectorManager();
     console.error(`Connecting with DSN: ${redactDSN(dsnData.dsn)}`);
     console.error(`DSN source: ${dsnData.source}`);
+    if (idData) {
+      console.error(`ID: ${idData.id} (from ${idData.source})`);
+    }
     if (dsnData.isDemo) {
       const initScript = getSqliteInMemorySetupSql();
       await connectorManager.connectWithDSN(dsnData.dsn, initScript);

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@bytebase/dbhub",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "Universal Database MCP Server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bytebase/dbhub.git"
+  },
   "main": "dist/index.js",
   "type": "module",
   "bin": {