opencode-agent
9aef200ac9
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.
122 lines
3.2 KiB
Markdown
122 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```jsonc
|
|
{
|
|
"plugins": [
|
|
{
|
|
"package": "./plugins/sqlite",
|
|
"options": {
|
|
"maxRows": 5000,
|
|
"maxBytes": 10485760,
|
|
"defaultMode": "create",
|
|
"allowedRoots": ["/srv/data"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 5. Restart the service and verify
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
> 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
|
|
|
|
```sh
|
|
# 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
|
|
```
|