# 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
```