opencode-postgres

library0.1.3jsnpmunverified

OpenCode plugin (v0.1.3) that adds a postgres_query tool for running SQL queries against a configured Postgres database. Ships TypeScript types. Requires @opencode-ai/plugin >=1.15.12. Key differentiator: tight integration with OpenCode's permission system, allowing per-query authorization. Supports read-only mode and connection string configuration. Release cadence: early development.

database

npm install opencode-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENCODE-POSTGRES

opencode-postgres

databasejavascriptv0.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import opencodePostgres from 'opencode-postgres'

✗ const opencodePostgres = require('opencode-postgres')

ESM-only; CommonJS require not supported.

PostgresPluginOptions

✓ import { PostgresPluginOptions } from 'opencode-postgres'

✗ import type { PostgresPluginOptions } from 'opencode-postgres'

Type symbol exported; both value and type imports work, but using 'import type' is unnecessary.

plugin

✓ import { plugin } from 'opencode-postgres'

✗ import { plugin } from 'opencode-postgres'; // Not a common mistake, but note: default export is also available.

Also exported as default; use 'import opencodePostgres from ...' for default.

Configures the Postgres plugin with a connection string, read-only mode, and permission prompt.

// Install: add to OpenCode config // .opencode.json or opencode.config.json { "$schema": "https://opencode.ai/config.json", "plugin": [ [ "opencode-postgres", { "connectionString": process.env.DATABASE_URL ?? 'postgres://user:password@localhost:5432/mydb', "readOnly": true } ] ], "permission": { "postgres_query": "ask" } }

Debug

Known issues

gotchaIf readOnly is false, the plugin still uses a read-write transaction; database-level permissions should be the source of truth.

fix

Set readOnly: true or restrict the database role to read-only access.

affects: >=0.0.0

breakingRequires @opencode-ai/plugin version >=1.15.12. Older OpenCode versions will fail to load the plugin.

fix

Update @opencode-ai/plugin to >=1.15.12.

affects: <0.1.0

gotchaThe permission key is 'postgres_query', not 'postgres' or 'query'.

fix

Use exactly 'postgres_query' in the permission config.

affects: >=0.0.0

gotchaIf permission.postgres_query is not configured, OpenCode's native fallback allows most permissions. Explicitly deny to restrict.

fix

Set permission.postgres_query to 'deny' if you want to block queries.

affects: >=0.0.0

deprecatedNo deprecated features known for v0.1.3; this warning is a placeholder.

fix

N/A

affects: >=0.0.0

Errors

Common errors & fixes

Error: Failed to load plugin 'opencode-postgres': Cannot find module '@opencode-ai/plugin'

Missing peer dependency @opencode-ai/plugin.

fix

Run `npm install @opencode-ai/plugin@>=1.15.12` in your project.

Error: Connection string is required

Missing 'connectionString' in plugin config.

fix

Add `"connectionString": "postgres://..."` to the plugin options.

Error: Permission denied: postgres_query

The plugin's permission is set to 'deny' or user did not grant permission.

fix

Set `"postgres_query": "allow"` in the permission config or choose 'always' in the prompt.

TypeError: Cannot read properties of undefined (reading 'query')

The plugin is not properly initialized or the tool is not available.

fix

Ensure the plugin is correctly configured in opencode config and OpenCode is restarted.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

@opencode-ai/pluginrequiredPeer dependency; required to register the plugin with OpenCode.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/vimtor/opencode-plugins ↗

packageopencode-postgres ↗

homepagehttps://github.com/vimtor/opencode-plugins/tree/main/packages/opencode-postgres#readme ↗