Koishi Plugin Database LevelDB

1.2.0 verified Sat Apr 25 auth: no javascript

A database service plugin for the Koishi bot framework that uses LevelDB as the storage backend. Current stable version is 1.2.0, released as part of the koishi-shangxue-plugins collection. It provides a lightweight, embedded key-value store with no external database dependencies, making it suitable for small to medium-sized chatbots. Key differentiators: high read/write performance due to LevelDB, minimal configuration, and automatic data persistence in local files. It fully integrates with Koishi's database abstraction layer, supporting table definition, CRUD operations, and querying.

Common errors

error Error: Cannot find module 'koishi-plugin-database-leveldb' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install koishi-plugin-database-leveldb' or add to package.json.

error TypeError: ctx.database.get is not a function ↓

cause Missing 'database' injection; plugin did not request database service.

fix

Ensure your plugin has 'export const inject = ['database']' and the database plugin is loaded before yours.

error LeveldbError: IO error: ... LOCK: No such file or directory ↓

cause Data directory not writable or parent directory missing.

fix

Create the 'data/database' directory or change the storage path via config.

error TypeError: Cannot read property 'extend' of undefined ↓

cause Database service not initialized; database plugin not properly loaded.

fix

Verify that the database plugin (koishi-plugin-database-leveldb) is installed and registered via app.plugin() before using ctx.model.

Warnings

gotcha Data persistence directory: Database files are stored in 'data/database/leveldb' relative to the Koishi working directory. Ensure the directory is writable and backed up if needed. ↓

fix Set 'database.leveldb.dir' in Koishi config to change the storage path.

gotcha No built-in migration: LevelDB schema is not enforced; changes to table definitions after data creation may lead to unexpected behavior or crashes. ↓

fix Plan schema carefully or manually clear the database (delete the directory) when modifying table structures.

gotcha Performance with large datasets: LevelDB performance degrades with millions of records; consider using SQLite or MySQL for larger bots. ↓

fix Switch to a more scalable database plugin if performance becomes an issue.

gotcha Concurrent access: LevelDB supports multiple processes but not recommended; running multiple Koishi instances with the same data directory can corrupt data. ↓

fix Use a single Koishi process per data directory.

Install

npm install koishi-plugin-database-leveldb

yarn add koishi-plugin-database-leveldb

pnpm add koishi-plugin-database-leveldb

Imports

default export

wrong

const KoishiDatabaseLeveldb = require('koishi-plugin-database-leveldb')

correct

import KoishiDatabaseLeveldb from 'koishi-plugin-database-leveldb'

CommonJS require() may not work if the package or its dependencies use ESM; recommended to use ESM imports.

apply function
wrong
```
function apply(ctx) { ... }
```
correct
```
export const inject = ['database']; export async function apply(ctx: Context) { ... }
```
Must use export for apply and inject with TypeScript module augmentation; ensure 'database' is in inject array.
Tables type augmentation
wrong
```
declare module 'koishi' { interface Tables { demo: DemoTable } }
```
correct
```
declare module 'koishi' { interface Tables { demo: DemoTable } }
```
The declaration must be inside a module augmentation, not a regular declaration. Ensure the module name is 'koishi'.

Quickstart

Shows how to define a table, inject database, and perform CRUD operations using Koishi's database interface with LevelDB backend.

import { Context } from 'koishi'

// Install plugin in your Koishi app
// app.plugin(require('koishi-plugin-database-leveldb'))
// or with ESM: import KoishiDatabaseLeveldb from 'koishi-plugin-database-leveldb'; app.plugin(KoishiDatabaseLeveldb)

// Then in a plugin:
declare module 'koishi' {
  interface Tables {
    todos: Todo
  }
}

interface Todo {
  id: number
  content: string
  completed: boolean
}

export const inject = ['database']

export async function apply(ctx: Context) {
  ctx.model.extend('todos', {
    id: 'integer',
    content: 'string',
    completed: 'boolean',
  }, { primary: 'id' })

  // Create a todo
  await ctx.database.create('todos', { id: 1, content: 'Buy milk', completed: false })

  // Read todos
  const todos = await ctx.database.get('todos', {})
  console.log(todos)

  // Update a todo
  await ctx.database.set('todos', { id: 1 }, { completed: true })

  // Delete a todo
  await ctx.database.remove('todos', { id: 1 })
}