version: "1.0.1" description: Connect DBHub to a database or fix a failing connection; also covers changing the DSN, write access, or multiple databases.

DBHub Setup

The database connection string (DSN) is entered in the plugin's configuration dialog and stored in Claude Code's secure storage. This plugin is read-only and caps results at 1000 rows.

Connecting or changing the database

1. Help the user build their DSN if they don't have one:

• PostgreSQL: postgres://user:password@localhost:5432/dbname
• MySQL: mysql://user:password@localhost:3306/dbname
• MariaDB: mariadb://user:password@localhost:3306/dbname
• SQL Server: sqlserver://user:password@localhost:1433/dbname
• Oracle: oracle://user:password@localhost:1521/FREEPDB1 (path is the service name)
• SQLite: sqlite:///absolute/path/to/database.db (no credentials)

Append ?sslmode=require for SSL (sslmode=disable for local databases). URL-encode special characters in the password. Recommend a least-privilege, read-only database account. Full DSN options (SQL Server named instances/NTLM, PostgreSQL cert verification): https://dbhub.ai/installation

1. Point them at the config dialog: run /plugin, open dbhub → configuration, and set the connection string there. The user should not paste the password into the chat.

1. Reconnect: run /mcp and reconnect the dbhub server (or restart Claude Code).

Troubleshooting a failing connection

• Test the DSN outside the plugin (redact the password in anything shown in chat):

``bash echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"setup-check","version":"0"}}}' | DBHUB_DSN='<dsn>' npx -y @bytebase/dbhub@latest --transport stdio --config <plugin-root>/dbhub.toml ` A JSON initialize` response means the config parsed and the server started; a connection error points at host/port/credentials/SSL.

• Common causes: database unreachable from this machine (host/port, VPN, firewall), wrong sslmode, un-encoded special characters in the password, a SQLite path that isn't absolute.
• If the server dies instantly with sh: dbhub: command not found, the npx cache entry is corrupted (concurrent npx runs can race during install). Find and remove the entry for @bytebase/dbhub under ~/.npm/_npx/*/package.json, then reconnect — npx will reinstall it cleanly.
• Requires Node.js >= 22.5.0 (node --version).

When this plugin isn't enough

The plugin covers one database, read-only. For write access, multiple databases, SSH tunnels, or custom tools, register DBHub directly with your own TOML config:

claude mcp add dbhub -- npx -y @bytebase/dbhub@latest --transport stdio --config /path/to/dbhub.toml

Offer to write that TOML for the user — format reference: https://dbhub.ai/config/toml. Suggest disabling this plugin's server afterwards to avoid two overlapping DBHub instances.