Files

T

opencode-agent 9aef200ac9 Add sqlite plugin: open/query/exec/script against .db files

Adds a single-file V2 plugin that exposes eight tools under the
`sqlite` namespace (open, close, list, query, exec, script, tables,
schema) so a model can read and write SQLite databases from a session.

- OpenCode discovers it automatically from ~/.config/opencode/plugins/.
- New runtime dependency: better-sqlite3 (installed in this repo's
  node_modules so the host's module resolution picks it up).
- README documents install, copy-to-another-machine, options, and
  troubleshooting; SETUP.md is a copy-paste checklist.
- Schema/options were trimmed down while authoring: the initial draft
  registered a no-op SQLite function on every open as a 'future hook';
  removed, it was dead code.

2026-10-08 17:03:48 +08:00

3.2 KiB

Raw Blame History

sqlite — install steps (copy-paste)

The plugin is a single TypeScript file. It needs two npm packages installed into the OpenCode config's own node_modules and one opencode.jsonc edit. The service must be restarted after the installs.

Prerequisites

OpenCode v2.x installed and on the PATH.
Node.js available (OpenCode already pulls this in).
On Linux: a working C toolchain (build-essential, python3, make on Debian/Ubuntu) — only required if the prebuilt better-sqlite3 binary does not match your platform.

1. Install the OpenCode plugin SDK at the matching version

cd ~/.config/opencode
npm i @opencode/plugin@$(opencode --version | sed 's/^v//')

A stale @opencode-ai/plugin (V1-era name) in node_modules is unrelated to the running host. Ignore it.

2. Install the SQLite driver

cd ~/.config/opencode
npm i better-sqlite3

Tested against better-sqlite3@13.0.3. Versions >= 11.0.0 expose the same surface and should work.

3. Drop the plugin files in place

If you are starting from the directory shipped here, just keep the existing ~/.config/opencode/plugins/sqlite/ directory. If you are copying it to another machine, copy the whole sqlite/ directory (index.ts and these docs) into the new machine's ~/.config/opencode/plugins/sqlite/.

4. Register the plugin

Edit ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "./plugins/sqlite"
  ]
}

If you already have a plugins array, append "./plugins/sqlite" rather than replacing it. A relative path here is resolved against the config file's directory, not the project working directory.

Optional, with configuration:

{
  "plugins": [
    {
      "package": "./plugins/sqlite",
      "options": {
        "maxRows": 5000,
        "maxBytes": 10485760,
        "defaultMode": "create",
        "allowedRoots": ["/srv/data"]
      }
    }
  ]
}

5. Restart the service and verify

opencode service restart
opencode plugin list

Expect a row whose ID is sqlite and whose SOURCE is local. If the plugin is not there, look at ~/.local/share/opencode/log/opencode.log and filter on sqlite.

6. Smoke test

In a session:

> open ":memory:" as alias "tmp"
> exec "CREATE TABLE hello(id INTEGER, msg TEXT); INSERT INTO hello VALUES (1, 'hi'), (2, 'world');" on "tmp"
> query "SELECT * FROM hello ORDER BY id" on "tmp"
> close "tmp"

The first call should print a confirmation. The second should report changes=2 (or similar — exact value depends on whether the CREATE counts). The third should print two rows.

Updating

To pick up a new version of @opencode/plugin after upgrading OpenCode, re-run step 1 with the new version. To pick up a newer better-sqlite3, re-run step 2. The plugin source itself is loaded fresh on every plugin reload — no rebuild step.

Removing

# 1. Drop the entry from opencode.jsonc
# 2. Remove the directory
rm -rf ~/.config/opencode/plugins/sqlite
# 3. (Optional) drop the dependency
cd ~/.config/opencode && npm rm better-sqlite3
# 4. Restart so the running service stops calling the tools
opencode service restart

3.2 KiB Raw Blame History