koishi-plugin-database-jsondb

1.2.0 verified Sat Apr 25 auth: no javascript

A lightweight JSON file-based database service plugin for Koishi chatbot framework. Current stable version is 1.2.0. It stores data in JSON files under `data/database/jsondb/` directory, with no external database dependencies, making it ideal for small bots and quick prototyping. Released as part of the Service More collection, it provides standard Koishi database operations (CRUD) with simple configuration. Compared to SQL-based alternatives, it sacrifices scalability for zero setup overhead. Ships TypeScript type definitions. Peer dependency on Koishi ^4.17.1.

Common errors

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

cause Plugin not installed or incorrect import path.

fix

Run npm install koishi-plugin-database-jsondb and ensure import is import DatabaseJsondb from 'koishi-plugin-database-jsondb'.

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

cause Missing `inject: ['database']` export or plugin not properly registered.

fix

Add export const inject = ['database'] to your plugin module and ensure app.plugin(databaseJsondb) is called before your plugin.

error Error: Invalid model definition: missing primary key ↓

cause Model extension did not specify a primary key.

fix

Add primary: 'fieldName' option in ctx.model.extend('table', fields, { primary: 'fieldName' }).

error ENOENT: no such file or directory, open '.../data/database/jsondb/demo.json' ↓

cause Storage directory does not exist; plugin should create it automatically, but permissions may be missing.

fix

Ensure the application has write permissions to the data directory. Create the directory manually if needed: mkdir -p data/database/jsondb.

Warnings

gotcha Data is stored in JSON files under `data/database/jsondb/`. Multiple instances or concurrent writes may cause data corruption. Not suitable for multi-process deployments. ↓

fix Use only in single-process environments. For clustering, consider a proper database like SQLite or MySQL.

gotcha Primary keys are required when extending a model. Without specifying a primary field, operations like `get` may return unexpected results. ↓

fix Always specify `primary` option in `ctx.model.extend(table, fields, { primary: 'field' })`.

deprecated The `database` plugin injection method may change in future Koishi versions. Refer to Koishi documentation for updates. ↓

fix Stay updated with Koishi changelogs. Currently `export const inject = ['database']` is correct.

breaking Version 1.0.0 changed the storage location from `data/jsondb/` to `data/database/jsondb/`. Existing data files may not be found. ↓

fix Migrate files manually from old directory to new one before upgrading.

Install

npm install koishi-plugin-database-jsondb

yarn add koishi-plugin-database-jsondb

pnpm add koishi-plugin-database-jsondb

Imports

default

wrong

const DatabaseJsondb = require('koishi-plugin-database-jsondb')

correct

import DatabaseJsondb from 'koishi-plugin-database-jsondb'

This is a Koishi plugin; it must be used with Koishi's `app.plugin(DatabaseJsondb)` pattern.

inject: database
```
export const inject = ['database']
```
Required in plugins that use database operations. Must be exported, not imported. This is provided by Koishi's dependency injection system.
ctx.database
```
ctx.database.get('table', { field: value })
```
Access database via context after injection. Available only after plugin is activated and database service is loaded.

Quickstart

Complete setup: install plugin, register it, declare table types, extend model, and use database operations (get, create, set) in a middleware.

// install: npm i koishi-plugin-database-jsondb
import { App } from 'koishi'
import databaseJsondb from 'koishi-plugin-database-jsondb'

const app = new App()
app.plugin(databaseJsondb)

app.plugin((ctx) => {
  // Declare table types
  declare module 'koishi' {
    interface Tables {
      demo: { id: string; name: string; count: number }
    }
  }

  // Inject database
  export const inject = ['database']

  // Extend model
  ctx.model.extend('demo', {
    id: 'string',
    name: 'string',
    count: 'integer'
  }, { primary: 'id' })

  // Use database
  ctx.middleware(async (session, next) => {
    const userId = session.userId
    let user = (await ctx.database.get('demo', { id: userId }))[0]
    if (!user) {
      user = { id: userId, name: 'new', count: 0 }
      await ctx.database.create('demo', user)
    } else {
      user.count++
      await ctx.database.set('demo', { id: userId }, { count: user.count })
    }
    return next()
  })
})

app.start()