Registry / database / koishi-plugin-database-jsondb

koishi-plugin-database-jsondb

library1.2.0jsnpmunverified

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.

database serialization

npm install koishi-plugin-database-jsondb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOISHI-PLUGIN-DATA

koishi-plugin-database-jsondb

databasejavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

default

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

✗ const DatabaseJsondb = require('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.

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()

Debug

Known issues

gotchaData 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.

affects: >=1.0.0

gotchaPrimary 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' })`.

affects: >=1.0.0

deprecatedThe `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.

affects: >=1.0.0 <2.0.0

breakingVersion 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.

affects: >=0.x <1.0.0

Errors

Common errors & fixes

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

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'`.

TypeError: ctx.database.get is not a function

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: Invalid model definition: missing primary key

Model extension did not specify a primary key.

fix

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

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

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

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

koishirequiredPeer dependency: requires Koishi framework v4.17.1+ for database service integrations.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/koishi-shangxue-plugins/service-more ↗

packagehttps://www.npmjs.com/package/koishi-plugin-database-jsondb ↗

homepagehttps://jsondb.service.more.koishi.chat ↗