Setup

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

2. 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.

3. 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):

  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.