DB2 CLP Runner

Run Db2 SQL scripts from VS Code, keep your connections and credentials organized, and — optionally — let an AI agent query Db2 through an MCP server without ever handing it your credentials.

Features

• Run from the editor — run the whole file, the selection, or several files at once. Output is parsed into the DB2 CLP output channel, with SQL errors surfaced as diagnostics.
• Connections panel — an activity-bar tree of your connections and their saved users. Switch the active connection, add or edit databases and users, and test a connection without leaving the tree. A connection shows green only when it has a password that can actually be used.
• Credentials in Secret Storage — passwords are never written to settings. Enter them once; they persist after they authenticate.
• MCP server — expose selected connections to MCP-capable agents (Claude Code, Codex, and others). The agent sends an alias and SQL; the extension resolves the user and password itself. See below.

Requirements

The extension runs SQL through db2cli from the IBM Data Server Driver (clidriver) or a Db2 client install. It does not bundle the driver, and it no longer uses the interactive db2 command-line processor.

Discovery checks db2clp.db2cliPath, IBM_DB_HOME, DB2_HOME, CLIDRIVER_HOME, DB2PATH on Windows, local node_modules/ibm_db/installer/clidriver folders, PATH, and conventional Db2 install roots such as ~/sqllib, /opt/ibm/clidriver, and C:\IBM\SQLLIB.

If db2cli is still not found, point the extension at your driver:

"db2clp.db2cliPath": "/opt/ibm/clidriver"

Either the clidriver root or the db2cli / db2cli.exe binary itself is accepted.

Getting started

1. Open the DB2 panel in the activity bar and choose Add Connection (+ in the panel title bar).
2. Fill in alias, host, port, and database, then add a user and password.
3. Open a .db2, .sql, or .ddl file and run it — the run button sits in the editor title bar by default.

Statement terminators are per file type: .db2 uses @, .sql and .ddl use ;. Change this with db2clp.fileExtensions.

MCP server

An agent gets an alias and a SQL string. It never receives a username, a password, or a connection string — those are resolved inside the extension from Secret Storage and passed to db2cli directly.

Access is denied by default and granted per saved user, not per connection. The level says what an agent may do; the user says who it does it as. Different users of one database can hold different levels — reader may be ReadOnly while admin is Full, or the reverse. Nothing is inferred from the username.

1. Set db2clp.connectionMode to singleShot. The server refuses to start in persistent mode, which puts the connection string in a visible terminal and would defeat the point.

2. Save credentials for the user you want to expose.

3. Open Edit User on that user and set MCP Access to ReadOnly or Full. This writes db2clp.mcpAccess to your user settings, which is machine-scoped — a cloned repository cannot grant itself database access, and a value placed in workspace settings is ignored:

   "db2clp.mcpAccess": { "testdb": { "db2inst1": "ReadOnly" } }
   

   Only the exact values ReadOnly and Full grant. Anything else — a typo, wrong case, a missing entry — denies. Setting the level back to None removes the grant.

4. Run DB2: Start MCP Server, or use the plug icon in the connections panel.

5. Run DB2: Write MCP Config (.mcp.json) to register the server with clients that read .mcp.json, such as Claude Code. The file contains no secrets: the transport is a user-private local socket, so there is no token to leak.

Two tools are exposed: list_connections and run_sql. list_connections reports one entry per granted user, identified by a handle of the form alias/user — that handle is what run_sql takes as its alias. Results are raw db2cli text — unreliable to parse mechanically, but perfectly readable to a language model.

Grants are re-checked on every call, so revoking access or deleting a password takes effect immediately rather than at the next restart.

What ReadOnly actually guarantees

ReadOnly is enforced by DB2, not by this extension. Grant it to a DB2 user that DB2 itself restricts to SELECT. The extension inspects SQL before running it, but that check is defence in depth and error messaging — it is not the security boundary.

It cannot be, and the limits are worth stating plainly:

• A function declared MODIFIES SQL DATA can be invoked from an ordinary SELECT and will write. No statement-level inspection can catch that.
• Data-change-table-references (SELECT ... FROM FINAL TABLE (INSERT ...)) are caught, along with OLD TABLE and NEW TABLE, but that is a specific pattern, not a general guarantee.
• Anything the inspector cannot classify is denied, including CALL, COMMIT and LOCK TABLE. Common table expressions are classified by the statement that follows the CTE list, so WITH ... SELECT reads and WITH ... INSERT writes.

If the granted user has write privileges in DB2, ReadOnly will stop the obvious cases and cannot promise more than that.

Commands

Per-connection actions — add or edit a user, set the active user, edit or delete a connection, test a connection — live on the right-click menu and inline buttons of the connections panel.

Settings

db2clp.connections, db2clp.activeConnection, and db2clp.currentSchema are written by the extension — manage connections through the panel rather than by editing settings.

Notes

• Results are raw db2cli output in the DB2 CLP channel. This is a script runner, not a result grid or schema browser — see the companion DB2 ODBC extension for those.
• persistent mode sends the connection string, including the password, to a visible terminal. Prefer singleShot if that matters to you; MCP requires it.

License

See the repository's LICENSE.