Database Admin for OpenCode

1.2.1 verified Thu Apr 23 auth: no javascript

database-admin is a multi-database tool plugin designed for the OpenCode AI platform, providing direct SQL access and management capabilities. It currently supports MySQL, MariaDB, PostgreSQL, SQL Server, and SQLite databases. The plugin, currently at version 1.2.1, is released as part of the OpenCode ecosystem. A key differentiating feature is its robust write protection mechanism, which mandates explicit user consent for all data modification or schema alteration operations. This consent is recorded with user identity for audit purposes. Connections are managed externally via a configuration file or through an auto-discovery mechanism that scans common project environment files (e.g., .env, appsettings.json), rather than programmatic API calls. It focuses on providing a secure, auditable, and configuration-flexible SQL interface within the OpenCode environment.

Common errors

error Write operation denied: Consent not granted. ↓

cause An attempt was made to execute a DML (e.g., INSERT, UPDATE, DELETE) or DDL (e.g., CREATE, ALTER, DROP) operation without first explicitly granting write consent.

fix

Grant consent for write operations by executing db { "action": "consent", "grant": true } within the OpenCode interface. You can specify a scope (e.g., "session", "global") for the consent duration.

error Database connection 'my_connection_name' not found. ↓

cause The connection name specified in the `connection` field of the `db` command does not exist in your `~/.config/opencode/db-connections.json` file, or the direct connection URL is malformed.

fix

Verify that my_connection_name is correctly defined in ~/.config/opencode/db-connections.json, or provide a valid, complete connection URL directly in the connection field of your query.

error Plugin 'database-admin' not enabled or found. ↓

cause The `database-admin` plugin is not correctly listed in the `plugins` array of your OpenCode configuration.

fix

Ensure that "database-admin" is included in the plugins array within your OpenCode configuration file (e.g., ~/.config/opencode/config.json).

Warnings

breaking All write operations (INSERT, UPDATE, DELETE, DROP, etc.) are strictly protected and require explicit user consent via `db { "action": "consent", "grant": true }` before execution. This is a mandatory safety feature and will block operations without prior consent. ↓

fix Execute `db { "action": "consent", "grant": true }` to enable write operations. Consider using `scope: "session"` for temporary consent or `scope: "global"` for permanent access during your workflow.

gotcha Granting write consent results in the logging of user identity (name, email, hostname) for audit purposes. Users should be aware of this data recording policy. ↓

fix Be mindful of the audit logging before granting consent. For sensitive operations, consider using a more restrictive consent scope like `"operation"` or `"session"` to limit exposure.

gotcha Database connections are primarily configured externally via `~/.config/opencode/db-connections.json` or through an auto-discovery mechanism scanning project files (.env, appsettings.json, etc.), rather than programmatic API calls within the OpenCode environment itself. ↓

fix Ensure connection files (e.g., `~/.config/opencode/db-connections.json`) are correctly formatted and accessible to OpenCode, or provide complete connection URLs directly within your `db` query commands.

Install

npm install database-admin

yarn add database-admin

pnpm add database-admin

Imports

Query Execution
wrong
```
import { query } from 'database-admin';
```
correct
```
db { "query": "SELECT * FROM users" }
```
This plugin is invoked via OpenCode's internal DSL for SQL operations; direct JavaScript/TypeScript module imports are not applicable.
Grant Write Consent
wrong
```
databaseAdmin.grantConsent();
```
correct
```
db { "action": "consent", "grant": true }
```
Plugin actions like granting consent are exclusively managed through the OpenCode `db` DSL within the OpenCode interface, not a programmatic API.
Discover Connections
wrong
```
const connections = require('database-admin').discoverConnections();
```
correct
```
db { "connection": "discover" }
```
All interactions with the database-admin plugin, including connection discovery, occur via the OpenCode `db` command structure.

Quickstart

Demonstrates how to execute basic SQL queries using the `db` command within the OpenCode environment, showing auto-discovery, named connections, and direct URL usage.

db { "query": "SELECT * FROM users LIMIT 5" }

-- Example with a specific connection defined in ~/.config/opencode/db-connections.json
db { "query": "SELECT * FROM products", "connection": "production_db" }

-- Example with a direct connection URL (use environment variables for credentials)
db { "query": "SELECT 1", "connection": "mysql://root:${process.env.DB_PASSWORD ?? ''}@localhost:3306/mydb" }